@nullplatform/plugin 0.0.3 → 0.0.4-alpha.1

package/README.md

@@ -8,7 +8,9 @@
     <br>
 </h2>
 
-TypeScript SDK for building nullplatform plugins. Handles gRPC transport (HashiCorp go-plugin protocol), action routing, `--describe`, and `--publish`.
+TypeScript SDK for building nullplatform plugins. Handles transport (gRPC
+go-plugin **and** subprocess-exec), action routing, action lifecycle reporting,
+`--describe`, and `--publish`.
 
 ## Install
 
@@ -16,6 +18,17 @@ TypeScript SDK for building nullplatform plugins. Handles gRPC transport (HashiC
 bun add @nullplatform/plugin
 ```
 
+## Layers
+
+The SDK is layered so the stable core is insulated from today's rough platform
+APIs:
+
+- **base** — the plugin runtime, transport (gRPC + subprocess-exec), and the
+  action-lifecycle *protocol*. Stable.
+- **compat** (`src/compat/`) — temporary shims for current APIs: token exchange,
+  action `PATCH` shapes. Each is deletable in isolation once the real API lands.
+- **goal layers** — `defineScope` today; `defineService`, `defineHook` next.
+
 ## Usage
 
 ### Scope plugin
@@ -36,18 +49,51 @@ defineScope({
     },
   },
 
+  // Optional — how the platform routes actions to your worker. Defaults to
+  // selector { package: <name> } and entrypoint /app/packages/<name>/entrypoint.
+  agent: {
+    selector: { package: "kubernetes-k3d" },
+  },
+
   actions: {
     "create-scope": {
       input: { type: "object" },
       handler: async (notification, emit) => {
+        emit({ stdout: "Provisioning…" });  // live message on the action + worker logs
         // provision infrastructure
-        return { domain: "app.k3d.local" };
+        return { domain: "app.k3d.local" };  // becomes the action results
       },
     },
   },
 });
 ```
 
+#### Actions
+
+`handler` is a plain `async (notification, emit) => result` (or a workflow
+chain). The SDK reports the action lifecycle automatically: `in_progress` on
+start, `success` with your returned object, or `failed` on throw. `emit({ stdout
+})` streams a live message onto the action in the UI.
+
+Well-known action slugs get their metadata (name, type, retryable, lifecycle)
+for free — `create-scope`, `delete-scope`, `update-scope`, `start-initial`,
+`start-blue-green`, `switch-traffic`, `finalize-blue-green`,
+`rollback-deployment`, `delete-deployment`, `diagnose-scope`,
+`diagnose-deployment`, `kill-instances`, `restart-pods`, `pause-autoscaling`,
+`resume-autoscaling`, `set-desired-instance-count`. For a **custom** action, use
+any slug and declare `name`/`type` inline:
+
+```ts
+"say-hello": { name: "Say Hello", type: "custom", input, handler },
+```
+
+#### Transport
+
+Agents run the compiled plugin directly (subprocess-exec): the action arrives in
+`NP_ACTION_CONTEXT`, the plugin runs it, reports status, prints the result, and
+exits. The gRPC go-plugin server is also supported for hosts that use it. You
+write handlers; the SDK picks the transport.
+
 ### Simple plugin (custom command)
 
 ```typescript
@@ -74,12 +120,17 @@ createPlugin({
 
 ## CLI integration
 
-Plugins are scaffolded with `np plugin init` and managed via mise tasks:
+Packages are scaffolded and driven with the `np package` commands, which are
+thin wrappers over the template's own 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
+np package init       # scaffold from a git template
+np package dev        # local dev UI + hot reload   (→ mise/bun run dev)
+np package test       # run tests                   (→ mise/bun run test)
+np package build --image   # build the worker image
+np package run        # run the worker as a real local agent (docker)
+np package publish    # register on the platform (specs + channel + artifact)
 ```
+
+`publish` reads the manifest from `--describe`, so the SDK owns the manifest
+shape and the CLI stays decoupled from it. See the CLI's `docs/packages.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nullplatform/plugin",
-  "version": "0.0.3",
+  "version": "0.0.4-alpha.1",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -14,6 +14,7 @@
   "dependencies": {
     "@grpc/grpc-js": "^1.13.0",
     "@grpc/proto-loader": "^0.7.0",
+    "config": "^4.4.2",
     "yaml": "^2.7.0"
   },
   "files": [
@@ -46,6 +47,7 @@
   },
   "devDependencies": {
     "@types/bun": "^1.2.0",
+    "@types/config": "^4.4.0",
     "json-schema-to-ts": "^3.1.1"
   }
 }

package/src/api.ts

@@ -14,13 +14,15 @@
 
 // ─── Configuration ───────────────────────────────────────────────────
 
+import { cfg } from "./config";
+
 const TIMEOUT_MS = 30_000;
 
 function getConfig() {
-  const apiUrl = process.env.NP_API_URL ?? "https://api.nullplatform.com";
-  const apiKey = process.env.NULLPLATFORM_APIKEY ?? "";
+  const apiUrl = cfg.apiUrl();
+  const apiKey = cfg.apiKey();
   if (!apiKey) {
-    throw new Error("NULLPLATFORM_APIKEY environment variable is not set");
+    throw new Error("NP_API_KEY is not set");
   }
   return { apiUrl, apiKey };
 }

package/src/compat/index.ts

@@ -0,0 +1,14 @@
+/**
+ * COMPAT LAYER — temporary shims for today's platform APIs.
+ *
+ * Anything in here exists only because a platform API is missing or awkward
+ * right now. Each shim should be deletable in isolation once the real API
+ * lands. The stable base + goal layers import from here; nothing here should
+ * depend on them.
+ */
+export {
+  patchActionStatus,
+  patchActionMessages,
+  type ActionStatus,
+  type ActionMessage,
+} from "./lifecycle";

package/src/compat/lifecycle.ts

@@ -0,0 +1,84 @@
+/**
+ * COMPAT LAYER — temporary. Delete as the platform APIs improve.
+ *
+ * Action lifecycle management, working around today's API shapes:
+ *   - PATCH /service/{serviceId}/action/{actionId} { status, results } for
+ *     in_progress / success / failed (no dedicated action-status endpoint yet).
+ *   - The API expects a Bearer *token*, so NP_API_KEY is exchanged for
+ *     an access token (POST /token) and cached (no direct api-key auth yet).
+ *
+ * Everything here is a shim for a rough edge. When the platform exposes a
+ * first-class action-lifecycle API, this whole file goes away and the base
+ * layer talks to it directly. Keep base-layer code OUT of here.
+ */
+
+import { cfg } from "../config";
+
+const API_URL = () => cfg.apiUrl();
+const API_KEY = () => cfg.apiKey();
+
+let cachedToken: string | undefined;
+
+async function getToken(): Promise<string> {
+  if (cachedToken) return cachedToken;
+  const res = await fetch(`${API_URL()}/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ apikey: API_KEY() }),
+  });
+  if (!res.ok) throw new Error(`Token exchange failed: ${res.status} ${res.statusText}`);
+  const data = (await res.json()) as { access_token?: string };
+  if (!data.access_token) throw new Error("Token exchange returned no access_token");
+  cachedToken = data.access_token;
+  return cachedToken;
+}
+
+export type ActionStatus = "in_progress" | "success" | "failed";
+export interface ActionMessage {
+  level: "info" | "warning" | "error";
+  message: string;
+}
+
+// patchAction PATCHes the action with any of status / results / messages. It's
+// the single entry point for reporting; status/messages helpers wrap it.
+async function patchAction(serviceId: string, actionId: string, body: Record<string, unknown>): Promise<void> {
+  if (!API_KEY()) return; // skip lifecycle if no API key (local dev / testing)
+  if (!serviceId || !actionId) return;
+
+  const token = await getToken();
+  const res = await fetch(`${API_URL()}/service/${serviceId}/action/${actionId}`, {
+    method: "PATCH",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`Action PATCH failed: ${res.status} ${res.statusText}${text ? ` — ${text}` : ""}`);
+  }
+}
+
+export async function patchActionStatus(
+  serviceId: string,
+  actionId: string,
+  status: ActionStatus,
+  results?: Record<string, unknown>,
+): Promise<void> {
+  const body: Record<string, unknown> = { status };
+  if (results) body.results = results;
+  return patchAction(serviceId, actionId, body);
+}
+
+// patchActionMessages appends log lines to the action (what shows in the UI as
+// the action runs) — the SDK equivalent of `np service-action exec --live-report`.
+export async function patchActionMessages(
+  serviceId: string,
+  actionId: string,
+  messages: ActionMessage[],
+): Promise<void> {
+  if (messages.length === 0) return;
+  return patchAction(serviceId, actionId, { messages });
+}

package/src/config.ts

@@ -0,0 +1,47 @@
+/**
+ * Central configuration — the ONE place the SDK reads environment.
+ *
+ * Values come from node-config (a package's `config/` dir: `default.json` for
+ * defaults + `custom-environment-variables.json` mapping env vars → keys), which
+ * is the single declarative place every env var is documented. If a package
+ * ships no config/ (or a key isn't mapped), we fall back to the raw env var and
+ * then a built-in default — so the SDK works with or without node-config.
+ *
+ * Nothing else in the SDK touches `process.env`. Import { cfg } from here.
+ */
+
+import config from "config";
+
+// read resolves a value in priority order: node-config → raw env var → default.
+// This module is the only place `process.env` is read.
+function read(key: string, envVar: string, fallback = ""): string {
+  try {
+    if (config.has(key)) {
+      const v = config.get(key);
+      if (v != null && v !== "") return String(v);
+    }
+  } catch {
+    // node-config not configured for this process (no config/ dir) — fall through.
+  }
+  return process.env[envVar] ?? fallback;
+}
+
+export const cfg = {
+  /** Platform API base URL. env: NP_API_URL */
+  apiUrl: () => read("api.url", "NP_API_URL", "https://api.nullplatform.com"),
+
+  /** Platform API key. env: NP_API_KEY */
+  apiKey: () => read("api.key", "NP_API_KEY"),
+
+  /** Executions/streaming API URL. env: NP_EXECUTIONS_API_URL */
+  executionsApiUrl: () => read("api.executionsUrl", "NP_EXECUTIONS_API_URL"),
+
+  /** Agent transport mode marker. env: NP_AGENT_PLUGIN */
+  agentMode: () => read("agent.mode", "NP_AGENT_PLUGIN"),
+
+  /** The action payload injected in subprocess-exec mode. env: NP_ACTION_CONTEXT */
+  actionContext: () => read("agent.actionContext", "NP_ACTION_CONTEXT"),
+
+  /** Path to a plugin manifest override. env: NP_PLUGIN_MANIFEST */
+  pluginManifest: () => read("plugin.manifest", "NP_PLUGIN_MANIFEST"),
+} as const;

package/src/internal/manifest.ts

@@ -8,6 +8,7 @@
 import { readFileSync, existsSync } from "fs";
 import { resolve } from "path";
 import YAML from "yaml";
+import { cfg } from "../config";
 import type { PluginManifest } from "../types";
 
 let registeredManifest: PluginManifest | null = null;
@@ -23,9 +24,10 @@ export function loadManifest(): PluginManifest {
     return registeredManifest;
   }
 
+  const manifestOverride = cfg.pluginManifest();
   const manifestPath = resolve(
-    process.env.NP_PLUGIN_MANIFEST || process.cwd(),
-    process.env.NP_PLUGIN_MANIFEST ? "" : "plugin.yaml",
+    manifestOverride || process.cwd(),
+    manifestOverride ? "" : "plugin.yaml",
   );
 
   if (!existsSync(manifestPath)) {

package/src/scope/describe.ts

@@ -6,7 +6,7 @@
  */
 
 import { getActionDefaults } from "./actions";
-import type { ScopeDefinition } from "./index";
+import { resolveAgentConfig, type ScopeDefinition } from "./index";
 
 export function handleDescribe(definition: ScopeDefinition): void {
   const actionSpecs: Record<string, unknown> = {};
@@ -33,6 +33,9 @@ export function handleDescribe(definition: ScopeDefinition): void {
     schema: definition.schema,
     actions: actionSpecs,
     uiSchema: definition.uiSchema,
+    // Routing config with defaults resolved from the name, so the CLI applies
+    // exactly what the scope declares instead of re-deriving conventions.
+    agent: resolveAgentConfig(definition),
   };
 
   const cleaned = JSON.parse(JSON.stringify(output));

package/src/scope/index.ts

@@ -30,7 +30,8 @@ import { InMemoryEngine } from "@nullplatform/workflow-engine-in-memory";
 import { getActionDefaults } from "./actions";
 import { handleDescribe } from "./describe";
 import { handlePublish } from "./publish";
-import { patchActionStatus } from "./lifecycle";
+import { patchActionStatus, patchActionMessages } from "../compat";
+import { cfg } from "../config";
 import type { NpJSONSchema } from "../schema";
 
 // ─── Types ───────────────────────────────────────────────────────────
@@ -84,10 +85,35 @@ export interface ScopeDefinition {
   /** JSONForms UISchema for rendering the capabilities form. */
   uiSchema?: object;
 
+  /**
+   * How the platform routes actions to the worker. Optional — sensible defaults
+   * are derived from `name`, so most scopes never set this. Override only for a
+   * custom selector or a non-standard worker entrypoint.
+   */
+  agent?: ScopeAgentConfig;
+
   /** Actions: schema (input/output) + handler, keyed by action slug. */
   actions: Record<string, ActionDefinition>;
 }
 
+/** Agent routing config for a scope. See {@link ScopeDefinition.agent}. */
+export interface ScopeAgentConfig {
+  /** Selector tags an agent must carry to handle this scope. Default: `{ package: <name> }`. */
+  selector?: Record<string, string>;
+  /** Path the agent execs in the worker image. Default: `/app/packages/<name>/entrypoint`. */
+  entrypoint?: string;
+}
+
+/** Fill agent config defaults from the scope name (the package slug). */
+export function resolveAgentConfig(definition: ScopeDefinition): Required<ScopeAgentConfig> {
+  const slug = definition.name;
+  const selector = definition.agent?.selector;
+  return {
+    selector: selector && Object.keys(selector).length > 0 ? selector : { package: slug },
+    entrypoint: definition.agent?.entrypoint || `/app/packages/${slug}/entrypoint`,
+  };
+}
+
 // ─── Exec payload parsing ────────────────────────────────────────────
 // The platform only supports "exec" channel type today. np-agent reroutes
 // exec commands to this plugin when the channel config includes NP_PLUGIN=scope
@@ -178,6 +204,69 @@ export function defineScope(definition: ScopeDefinition): void {
     command_types: ["scope"],
   });
 
+  // Subprocess exec mode: agents that run this binary directly (no gRPC host)
+  // pass the action in the NP_ACTION_CONTEXT env var. Run the one action, report
+  // its lifecycle status, print the result, and exit.
+  const execCtx = cfg.actionContext();
+  if (execCtx && cfg.agentMode() !== "np-agent-v1") {
+    void (async () => {
+      let out: ExecuteResult;
+      let serviceId = "";
+      let actionId = "";
+      let lifecycle = false;
+      try {
+        const raw = JSON.parse(execCtx);
+        const notification: Notification = raw.notification ?? raw;
+        serviceId = notification.service?.id ?? "";
+        actionId = notification.id ?? "";
+        // emit forwards handler output to stderr (worker logs) AND, as action
+        // messages, to the platform so they show live on the action.
+        const emit = (o: { stdout?: string; stderr?: string }) => {
+          if (o?.stdout) {
+            process.stderr.write(o.stdout);
+            void patchActionMessages(serviceId, actionId, [{ level: "info", message: o.stdout.trimEnd() }]).catch(() => {});
+          }
+          if (o?.stderr) {
+            process.stderr.write(o.stderr);
+            void patchActionMessages(serviceId, actionId, [{ level: "error", message: o.stderr.trimEnd() }]).catch(() => {});
+          }
+        };
+        const actionSlug = resolveActionSlug(notification, notification.type ?? "");
+        const actionDef = definition.actions[actionSlug];
+        if (!actionDef) throw new Error(`Unknown action: ${actionSlug}`);
+        lifecycle = getActionDefaults(actionSlug).lifecycle;
+        if (lifecycle && actionId) {
+          await patchActionStatus(serviceId, actionId, "in_progress").catch(() => {});
+        }
+        let data: unknown;
+        if (isWorkflowChain(actionDef.handler)) {
+          const observer = new StreamingExecutionObserver(emit, { apiUrl: cfg.executionsApiUrl() });
+          observer.emitPlan(actionDef.handler.toGraph());
+          const engine = new InMemoryEngine({ observer });
+          const wf = await actionDef.handler.run(notification, { engine, timeoutMs: 10 * 60 * 1000 });
+          if (wf.status !== "completed") throw new Error(wf.error?.message ?? `Workflow ${wf.status}`);
+          data = wf.output;
+        } else {
+          data = await actionDef.handler(notification, emit);
+        }
+        if (lifecycle && actionId) {
+          const results = data && typeof data === "object" ? (data as Record<string, unknown>) : undefined;
+          await patchActionStatus(serviceId, actionId, "success", results).catch(() => {});
+        }
+        out = { success: true, data };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (lifecycle && actionId) {
+          await patchActionStatus(serviceId, actionId, "failed", { error: message }).catch(() => {});
+        }
+        out = { success: false, error: message, errorCode: "EXECUTION_ERROR" };
+      }
+      process.stdout.write(JSON.stringify(out));
+      process.exit(out.success ? 0 : 1);
+    })();
+    return;
+  }
+
   const plugin = createPlugin({
     async execute(req: ExecuteRequest): Promise<ExecuteResult> {
       // Handle both native "scope" and legacy "exec" command types
@@ -205,9 +294,10 @@ export function defineScope(definition: ScopeDefinition): void {
 
       const defaults = getActionDefaults(actionSlug);
       const actionId = notification.id;
+      const serviceId = notification.service?.id ?? "";
 
       if (defaults.lifecycle && actionId) {
-        await patchActionStatus(actionId, "in_progress").catch((err) => {
+        await patchActionStatus(serviceId, actionId, "in_progress").catch((err) => {
           console.error(`[defineScope] Failed to patch action status: ${err.message}`);
         });
       }
@@ -218,7 +308,7 @@ export function defineScope(definition: ScopeDefinition): void {
         if (isWorkflowChain(actionDef.handler)) {
           // Workflow chain: emit plan, run with engine
           const observer = new StreamingExecutionObserver(req.emit, {
-            apiUrl: process.env.NP_EXECUTIONS_API_URL,
+            apiUrl: cfg.executionsApiUrl(),
           });
           observer.emitPlan(actionDef.handler.toGraph());
 
@@ -235,7 +325,8 @@ export function defineScope(definition: ScopeDefinition): void {
         }
 
         if (defaults.lifecycle && actionId) {
-          await patchActionStatus(actionId, "completed").catch((err) => {
+          const results = result && typeof result === "object" ? (result as Record<string, unknown>) : undefined;
+          await patchActionStatus(serviceId, actionId, "success", results).catch((err) => {
             console.error(`[defineScope] Failed to patch action status: ${err.message}`);
           });
         }
@@ -245,7 +336,7 @@ export function defineScope(definition: ScopeDefinition): void {
         const message = error instanceof Error ? error.message : String(error);
 
         if (defaults.lifecycle && actionId) {
-          await patchActionStatus(actionId, "failed", message).catch((err) => {
+          await patchActionStatus(serviceId, actionId, "failed", { error: message }).catch((err) => {
             console.error(`[defineScope] Failed to patch action status: ${err.message}`);
           });
         }

package/src/scope/publish.ts

@@ -15,6 +15,7 @@
 
 import { $ } from "bun";
 import { getActionDefaults } from "./actions";
+import { cfg } from "../config";
 import type { ScopeDefinition } from "./index";
 
 export async function handlePublish(definition: ScopeDefinition): Promise<void> {
@@ -161,7 +162,7 @@ export async function handlePublish(definition: ScopeDefinition): Promise<void>
   console.log(`  ${existingScopeType ? "↻" : "✓"} Scope type: ${scopeTypeId}`);
 
   // 4. Dev notification channel (upsert by description tag)
-  const apiKey = process.env.NP_API_KEY;
+  const apiKey = cfg.apiKey();
   if (!apiKey) {
     console.error("\n⚠ Skipping notification channel — NP_API_KEY not set");
     console.error("  Set it and re-run, or create the channel manually via the UI");

package/src/scope/lifecycle.ts

@@ -1,39 +0,0 @@
-/**
- * Action lifecycle management.
- *
- * PATCHes service action status via the platform API.
- * Mirrors what `np service-action exec` does:
- *   - PATCH status: "in_progress" on start
- *   - PATCH status: "completed" or "failed" on end
- */
-
-const API_URL = () => process.env.NP_API_URL ?? "https://api.nullplatform.com";
-const API_KEY = () => process.env.NULLPLATFORM_APIKEY ?? "";
-
-export async function patchActionStatus(
-  actionId: string,
-  status: "in_progress" | "completed" | "failed",
-  error?: string,
-): Promise<void> {
-  const apiKey = API_KEY();
-  if (!apiKey) return; // skip lifecycle if no API key (local dev / testing)
-
-  const body: Record<string, unknown> = { status };
-  if (error) {
-    body.results = { error };
-  }
-
-  const res = await fetch(`${API_URL()}/service/action/${actionId}`, {
-    method: "PATCH",
-    headers: {
-      Authorization: `Bearer ${apiKey}`,
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify(body),
-  });
-
-  if (!res.ok) {
-    const text = await res.text().catch(() => "");
-    throw new Error(`Lifecycle PATCH ${status} failed: ${res.status} ${res.statusText}${text ? ` — ${text}` : ""}`);
-  }
-}