@nullplatform/plugin 0.0.4-alpha.1 → 0.0.4-alpha.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nullplatform/plugin",
-  "version": "0.0.4-alpha.1",
+  "version": "0.0.4-alpha.2",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -9,7 +9,9 @@
     "./schema": "./src/schema.ts",
     "./scope": "./src/scope/index.ts",
     "./testing": "./src/testing/index.ts",
-    "./workflow": "./src/workflow.ts"
+    "./workflow": "./src/workflow.ts",
+    "./service": "./src/service/index.ts",
+    "./platform": "./src/platform/index.ts"
   },
   "dependencies": {
     "@grpc/grpc-js": "^1.13.0",

package/src/config.ts

@@ -39,6 +39,14 @@ export const cfg = {
   /** Agent transport mode marker. env: NP_AGENT_PLUGIN */
   agentMode: () => read("agent.mode", "NP_AGENT_PLUGIN"),
 
+  /**
+   * Execution mode: "dev" | "test" | "" (production/agent). Set explicitly by
+   * `np package dev` / `np package test`. When "dev" or "test" the SDK uses the
+   * in-memory platform client and NEVER touches the real API — even if an API
+   * key is present in the environment. env: NP_MODE
+   */
+  mode: () => read("mode", "NP_MODE"),
+
   /** The action payload injected in subprocess-exec mode. env: NP_ACTION_CONTEXT */
   actionContext: () => read("agent.actionContext", "NP_ACTION_CONTEXT"),
 

package/src/internal/grpc-server.ts

@@ -22,11 +22,13 @@
 
 import * as grpc from "@grpc/grpc-js";
 import * as protoLoader from "@grpc/proto-loader";
-import { unlinkSync } from "fs";
+import { unlinkSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
-import { join, resolve, dirname } from "path";
-import { fileURLToPath } from "url";
+import { join } from "path";
 import type { PluginHandler, ExecuteRequest, PluginManifest } from "../types";
+// Embed the proto as text so it survives `bun build --compile` (a compiled
+// binary has no plugin.proto on disk next to the source). Works from source too.
+import protoSource from "./plugin.proto" with { type: "text" };
 
 const MAGIC_COOKIE_KEY = "NP_AGENT_PLUGIN";
 const MAGIC_COOKIE_VALUE = "np-agent-v1";
@@ -158,12 +160,11 @@ export function startGrpcServer(
     handler,
     manifest,
   };
-  // Resolve proto path — import.meta.dir is Bun-only; fall back to
-  // import.meta.url (standard ESM) for Node.js compatibility.
-  const protoDir = typeof import.meta.dir === "string"
-    ? import.meta.dir
-    : dirname(fileURLToPath(import.meta.url));
-  const protoPath = resolve(protoDir, "plugin.proto");
+  // @grpc/proto-loader loads from a file path, so materialize the embedded proto
+  // text to a temp file. This is the one path that works both from source and
+  // from a compiled single-file binary.
+  const protoPath = join(tmpdir(), `np-plugin-${process.pid}.proto`);
+  writeFileSync(protoPath, protoSource);
   const packageDefinition = protoLoader.loadSync(protoPath, {
     keepCase: true,
     longs: String,

package/src/internal/manifest.ts

@@ -19,7 +19,11 @@ export function registerManifest(manifest: PluginManifest): void {
 }
 
 export function loadManifest(): PluginManifest {
-  // If a manifest was registered in-memory (by defineScope), use it
+  // Two ways a plugin declares its manifest (name/version/command_types):
+  //   1. defineScope() registers it in-memory at import time — the common path;
+  //      scope plugins never need a plugin.yaml.
+  //   2. Raw createPlugin() plugins (no defineScope) fall back to a plugin.yaml
+  //      file on disk. Override its path with NP_PLUGIN_MANIFEST.
   if (registeredManifest) {
     return registeredManifest;
   }

package/src/platform/client.ts

@@ -0,0 +1,109 @@
+/**
+ * PlatformClient — the ONE port through which a plugin talks to the control
+ * plane. A handler never calls the platform API directly; the SDK injects a
+ * client and swaps the implementation by mode:
+ *
+ *   - HttpPlatformClient   real API calls (the dockerized agent / `np package run`)
+ *   - InMemoryPlatformClient   records calls, prints locally, never networks
+ *                              (`np package dev`, `np package test`)
+ *
+ * This is the pattern every comparable system converges on (Temporal activity
+ * context, Crossplane ExternalClient, Terraform provider client, go-plugin host
+ * services): local dev is isolated by construction, not by the accident of a
+ * missing credential.
+ */
+
+import { cfg } from "../config";
+import { patchActionStatus, patchActionMessages, type ActionStatus } from "../compat";
+
+export type { ActionStatus };
+export type LogStream = "stdout" | "stderr";
+
+export interface PlatformClient {
+  /** How this client is wired — "http" hits the real API, "memory" stays local. */
+  readonly mode: "http" | "memory";
+
+  /** Report an action lifecycle transition (in_progress → success/failed). */
+  transitionAction(
+    serviceId: string,
+    actionId: string,
+    status: ActionStatus,
+    results?: Record<string, unknown>,
+  ): Promise<void>;
+
+  /** Append a log line to the action (shows live in the UI as it runs). */
+  emitLog(serviceId: string, actionId: string, line: string, stream: LogStream): Promise<void>;
+}
+
+/** Real client: talks to the nullplatform API. Used by the agent / `np package run`. */
+export class HttpPlatformClient implements PlatformClient {
+  readonly mode = "http" as const;
+
+  async transitionAction(
+    serviceId: string,
+    actionId: string,
+    status: ActionStatus,
+    results?: Record<string, unknown>,
+  ): Promise<void> {
+    await patchActionStatus(serviceId, actionId, status, results);
+  }
+
+  async emitLog(serviceId: string, actionId: string, line: string, stream: LogStream): Promise<void> {
+    const message = line.trimEnd();
+    if (!message) return;
+    // Local visibility: logs go to STDERR (stdout is reserved for the result
+    // JSON the agent parses). This is the standard data-on-stdout /
+    // logs-on-stderr split. The platform UI gets the same line as a properly
+    // leveled action message below.
+    process.stderr.write(message + "\n");
+    await patchActionMessages(serviceId, actionId, [
+      { level: stream === "stderr" ? "error" : "info", message },
+    ]);
+  }
+}
+
+/**
+ * Fake client: records every call and echoes logs to the terminal, but makes NO
+ * network calls. Used for `np package dev` and tests so a plugin runs fully
+ * local. Exposed calls are inspectable via `.calls` for assertions.
+ */
+export class InMemoryPlatformClient implements PlatformClient {
+  readonly mode = "memory" as const;
+
+  readonly calls: Array<
+    | { kind: "transition"; actionId: string; status: ActionStatus; results?: Record<string, unknown> }
+    | { kind: "log"; actionId: string; line: string; stream: LogStream }
+  > = [];
+
+  constructor(private readonly opts: { echo?: boolean } = { echo: true }) {}
+
+  async transitionAction(
+    _serviceId: string,
+    actionId: string,
+    status: ActionStatus,
+    results?: Record<string, unknown>,
+  ): Promise<void> {
+    this.calls.push({ kind: "transition", actionId, status, results });
+    if (this.opts.echo) process.stderr.write(`  • action ${status}\n`);
+  }
+
+  async emitLog(_serviceId: string, actionId: string, line: string, stream: LogStream): Promise<void> {
+    const message = line.trimEnd();
+    if (!message) return;
+    this.calls.push({ kind: "log", actionId, line: message, stream });
+    if (this.opts.echo) process.stderr.write(`  → ${message}\n`);
+  }
+}
+
+/**
+ * Pick the client for the current process. Explicit dev/test mode ALWAYS returns
+ * the in-memory fake — even when NP_API_KEY is set — so local runs can never
+ * mutate the real platform. Only a real agent run (no dev mode + a key present)
+ * gets the HTTP client.
+ */
+export function resolvePlatformClient(): PlatformClient {
+  const mode = cfg.mode();
+  if (mode === "dev" || mode === "test") return new InMemoryPlatformClient();
+  if (!cfg.apiKey()) return new InMemoryPlatformClient(); // no creds → stay local
+  return new HttpPlatformClient();
+}

package/src/platform/index.ts

@@ -0,0 +1,8 @@
+export {
+  type PlatformClient,
+  type ActionStatus,
+  type LogStream,
+  HttpPlatformClient,
+  InMemoryPlatformClient,
+  resolvePlatformClient,
+} from "./client";

package/src/scope/index.ts

@@ -30,7 +30,7 @@ import { InMemoryEngine } from "@nullplatform/workflow-engine-in-memory";
 import { getActionDefaults } from "./actions";
 import { handleDescribe } from "./describe";
 import { handlePublish } from "./publish";
-import { patchActionStatus, patchActionMessages } from "../compat";
+import { resolvePlatformClient } from "../platform";
 import { cfg } from "../config";
 import type { NpJSONSchema } from "../schema";
 
@@ -210,6 +210,7 @@ export function defineScope(definition: ScopeDefinition): void {
   const execCtx = cfg.actionContext();
   if (execCtx && cfg.agentMode() !== "np-agent-v1") {
     void (async () => {
+      const platform = resolvePlatformClient();
       let out: ExecuteResult;
       let serviceId = "";
       let actionId = "";
@@ -219,24 +220,19 @@ export function defineScope(definition: ScopeDefinition): void {
         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.
+        // emit forwards handler output to the platform as action messages (shown
+        // live on the action). It routes through the injected client, so in dev
+        // it's recorded locally and never touches the API.
         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(() => {});
-          }
+          if (o?.stdout) void platform.emitLog(serviceId, actionId, o.stdout, "stdout").catch(() => {});
+          if (o?.stderr) void platform.emitLog(serviceId, actionId, o.stderr, "stderr").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(() => {});
+          await platform.transitionAction(serviceId, actionId, "in_progress").catch(() => {});
         }
         let data: unknown;
         if (isWorkflowChain(actionDef.handler)) {
@@ -251,13 +247,13 @@ export function defineScope(definition: ScopeDefinition): void {
         }
         if (lifecycle && actionId) {
           const results = data && typeof data === "object" ? (data as Record<string, unknown>) : undefined;
-          await patchActionStatus(serviceId, actionId, "success", results).catch(() => {});
+          await platform.transitionAction(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(() => {});
+          await platform.transitionAction(serviceId, actionId, "failed", { error: message }).catch(() => {});
         }
         out = { success: false, error: message, errorCode: "EXECUTION_ERROR" };
       }
@@ -267,6 +263,7 @@ export function defineScope(definition: ScopeDefinition): void {
     return;
   }
 
+  const platform = resolvePlatformClient();
   const plugin = createPlugin({
     async execute(req: ExecuteRequest): Promise<ExecuteResult> {
       // Handle both native "scope" and legacy "exec" command types
@@ -297,7 +294,7 @@ export function defineScope(definition: ScopeDefinition): void {
       const serviceId = notification.service?.id ?? "";
 
       if (defaults.lifecycle && actionId) {
-        await patchActionStatus(serviceId, actionId, "in_progress").catch((err) => {
+        await platform.transitionAction(serviceId, actionId, "in_progress").catch((err) => {
           console.error(`[defineScope] Failed to patch action status: ${err.message}`);
         });
       }
@@ -326,7 +323,7 @@ export function defineScope(definition: ScopeDefinition): void {
 
         if (defaults.lifecycle && actionId) {
           const results = result && typeof result === "object" ? (result as Record<string, unknown>) : undefined;
-          await patchActionStatus(serviceId, actionId, "success", results).catch((err) => {
+          await platform.transitionAction(serviceId, actionId, "success", results).catch((err) => {
             console.error(`[defineScope] Failed to patch action status: ${err.message}`);
           });
         }
@@ -336,7 +333,7 @@ export function defineScope(definition: ScopeDefinition): void {
         const message = error instanceof Error ? error.message : String(error);
 
         if (defaults.lifecycle && actionId) {
-          await patchActionStatus(serviceId, actionId, "failed", { error: message }).catch((err) => {
+          await platform.transitionAction(serviceId, actionId, "failed", { error: message }).catch((err) => {
             console.error(`[defineScope] Failed to patch action status: ${err.message}`);
           });
         }

package/src/service/describe.ts

@@ -0,0 +1,43 @@
+/**
+ * --describe for a service package. Prints the manifest as JSON. The `kind:
+ * "service"` marker tells the CLI to register a dependency service_specification
+ * (with use_default_actions) instead of a scope + scope type.
+ */
+
+import { resolveAgentConfig } from "../scope";
+import type { ServiceDefinition } from "./index";
+
+export function handleServiceDescribe(definition: ServiceDefinition): void {
+  // Only CUSTOM actions are described — the platform generates create/update/
+  // delete when useDefaultActions is on, so we don't ship specs for them.
+  const defaultTypes = new Set(["create", "update", "delete"]);
+  const actionSpecs: Record<string, unknown> = {};
+  for (const [slug, action] of Object.entries(definition.actions)) {
+    if (definition.useDefaultActions !== false && defaultTypes.has(slug)) continue;
+    actionSpecs[slug] = {
+      name: action.name ?? slug,
+      type: action.type ?? "custom",
+      retryable: action.retryable ?? false,
+      lifecycle: true,
+      input: action.input,
+      output: action.output,
+    };
+  }
+
+  const output = {
+    kind: "service",
+    name: definition.name,
+    version: definition.version,
+    description: definition.description,
+    category: definition.category,
+    provider: definition.provider,
+    schema: definition.schema,
+    uiSchema: definition.uiSchema,
+    useDefaultActions: definition.useDefaultActions ?? true,
+    assignableTo: definition.assignableTo ?? "any",
+    actions: actionSpecs,
+    agent: resolveAgentConfig(definition as any),
+  };
+
+  console.log(JSON.stringify(JSON.parse(JSON.stringify(output)), null, 2));
+}

package/src/service/index.ts

@@ -0,0 +1,173 @@
+/**
+ * defineService() — define a self-describing SERVICE package.
+ *
+ * A service is an application *dependency* (a database, cache, queue, …), not a
+ * deployment target. It differs from a scope:
+ *   - the service_specification is `type: "dependency"` (no scope type),
+ *   - with `useDefaultActions` the platform auto-generates create/update/delete
+ *     action specs from the schema — you only write handlers, not specs,
+ *   - action slugs are dynamic (`create-<name>`), so handlers are keyed by the
+ *     action TYPE (create/update/delete) or a custom slug.
+ *
+ * The runtime (subprocess-exec + gRPC, lifecycle reporting) mirrors defineScope.
+ */
+
+import { createPlugin } from "../create-plugin";
+import type { ExecuteRequest, ExecuteResult } from "../types";
+import { registerManifest } from "../internal/manifest";
+import { StreamingExecutionObserver } from "../workflow";
+import { InMemoryEngine } from "@nullplatform/workflow-engine-in-memory";
+import { resolvePlatformClient } from "../platform";
+import { cfg } from "../config";
+import { resolveAgentConfig, type ScopeAgentConfig, type ActionDefinition, type Notification } from "../scope";
+import { handleServiceDescribe } from "./describe";
+import type { NpJSONSchema } from "../schema";
+
+export interface ServiceDefinition {
+  name: string;
+  version: string;
+  description?: string;
+  category?: string;
+  provider?: string;
+
+  /** JSON Schema for the service's attributes (its configurable properties). */
+  schema: NpJSONSchema;
+
+  /** JSONForms UISchema for the attributes form. */
+  uiSchema?: object;
+
+  /**
+   * Let the platform auto-generate create/update/delete action specs from the
+   * schema (default true). Set false to declare all action specs yourself.
+   */
+  useDefaultActions?: boolean;
+
+  /** Where the service can be assigned. Default "any". */
+  assignableTo?: "any" | "dimension" | "scope";
+
+  /** How the platform routes actions to the worker. Defaults from `name`. */
+  agent?: ScopeAgentConfig;
+
+  /**
+   * Handlers, keyed by action type (`create`/`update`/`delete`) for the default
+   * actions, and by slug for any custom action.
+   */
+  actions: Record<string, ActionDefinition>;
+}
+
+function isWorkflowChain(handler: unknown): handler is { run: Function; toGraph: Function } {
+  return !!handler && typeof (handler as any).run === "function" && typeof (handler as any).toGraph === "function";
+}
+
+// resolveServiceHandler maps a notification to a handler. Default actions arrive
+// with a dynamic slug (`create-<name>`) but a stable `type` (create/update/
+// delete), so we try: exact slug → action type → the type-prefixed slug.
+function resolveServiceHandler(def: ServiceDefinition, notification: Notification): { key: string; action?: ActionDefinition } {
+  const slug = notification.slug || notification.specification?.slug || "";
+  const type = String((notification as any).type ?? "");
+  if (slug && def.actions[slug]) return { key: slug, action: def.actions[slug] };
+  if (type && def.actions[type]) return { key: type, action: def.actions[type] };
+  // "create-postgres" → "create"
+  const prefix = slug.split("-")[0];
+  if (prefix && def.actions[prefix]) return { key: prefix, action: def.actions[prefix] };
+  return { key: slug || type };
+}
+
+export function defineService(definition: ServiceDefinition): void {
+  if (process.argv.includes("--describe")) {
+    handleServiceDescribe(definition);
+    process.exit(0);
+  }
+
+  registerManifest({
+    name: definition.name,
+    version: definition.version,
+    command_types: ["service"],
+  });
+
+  // Subprocess-exec mode (how the agent runs the worker): the action arrives in
+  // NP_ACTION_CONTEXT; run it, report lifecycle, print the result, exit.
+  const execCtx = cfg.actionContext();
+  if (execCtx && cfg.agentMode() !== "np-agent-v1") {
+    void (async () => {
+      const platform = resolvePlatformClient();
+      let out: ExecuteResult;
+      let serviceId = "";
+      let actionId = "";
+      try {
+        const raw = JSON.parse(execCtx);
+        const notification: Notification = raw.notification ?? raw;
+        serviceId = notification.service?.id ?? "";
+        actionId = notification.id ?? "";
+        const emit = (o: { stdout?: string; stderr?: string }) => {
+          if (o?.stdout) void platform.emitLog(serviceId, actionId, o.stdout, "stdout").catch(() => {});
+          if (o?.stderr) void platform.emitLog(serviceId, actionId, o.stderr, "stderr").catch(() => {});
+        };
+        const { key, action } = resolveServiceHandler(definition, notification);
+        if (!action) throw new Error(`Unknown service action: ${key}`);
+        if (actionId) await platform.transitionAction(serviceId, actionId, "in_progress").catch(() => {});
+        let data: unknown;
+        if (isWorkflowChain(action.handler)) {
+          const observer = new StreamingExecutionObserver(emit, { apiUrl: cfg.executionsApiUrl() });
+          observer.emitPlan((action.handler as any).toGraph());
+          const engine = new InMemoryEngine({ observer });
+          const wf = await (action.handler as any).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 (action.handler as any)(notification, emit);
+        }
+        if (actionId) {
+          const results = data && typeof data === "object" ? (data as Record<string, unknown>) : undefined;
+          await platform.transitionAction(serviceId, actionId, "success", results).catch(() => {});
+        }
+        out = { success: true, data };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (actionId) await platform.transitionAction(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;
+  }
+
+  // gRPC host path (dev / np-agent-v1).
+  const platform = resolvePlatformClient();
+  const plugin = createPlugin({
+    async execute(req: ExecuteRequest): Promise<ExecuteResult> {
+      let notification: Notification;
+      try {
+        const raw = JSON.parse(req.payload.toString("utf-8"));
+        notification = raw.notification ?? raw;
+      } catch {
+        return { success: false, error: "invalid payload", errorCode: "MISSING_CONTEXT" };
+      }
+      const { key, action } = resolveServiceHandler(definition, notification);
+      if (!action) return { success: false, error: `Unknown service action: ${key}`, errorCode: "UNKNOWN_ACTION" };
+      const actionId = notification.id;
+      const serviceId = notification.service?.id ?? "";
+      if (actionId) await platform.transitionAction(serviceId, actionId, "in_progress").catch(() => {});
+      try {
+        const result = await (action.handler as any)(notification, req.emit);
+        if (actionId) {
+          const results = result && typeof result === "object" ? (result as Record<string, unknown>) : undefined;
+          await platform.transitionAction(serviceId, actionId, "success", results).catch(() => {});
+        }
+        return { success: true, data: result };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (actionId) await platform.transitionAction(serviceId, actionId, "failed", { error: message }).catch(() => {});
+        return { success: false, error: message, errorCode: "EXECUTION_ERROR" };
+      }
+    },
+  });
+  plugin.start();
+}
+
+export { resolveAgentConfig };
+// Author-facing types: a service handler receives the action notification and an
+// `emit` callback. `ServiceActionInput` is the notification shape (aliased from
+// the shared Notification type) so action files read as service code.
+export type { Notification as ServiceActionInput, ActionDefinition, ScopeAgentConfig } from "../scope";

package/src/testing/plugin-client.ts

@@ -53,6 +53,10 @@ export async function startPluginProcess(
       ...process.env,
       ...opts?.env,
       NP_AGENT_PLUGIN: "np-agent-v1",
+      // This helper only ever runs a plugin for local dev/test (the real agent
+      // execs the binary directly). Force in-memory platform mode so a dev/test
+      // run can never hit the real API, even if NP_API_KEY is in the env.
+      NP_MODE: process.env.NP_MODE || "dev",
     },
     stdout: "pipe",
     stderr: "pipe",