@kahitsan/plugin-sdk 0.2.0-staging.37 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahitsan/plugin-sdk",
-  "version": "0.2.0-staging.37",
+  "version": "0.2.0",
   "description": "THE single public author surface for Hilinga plugins: createPlugin, auth guards, the workspace-scoped data surface (makeDataSurface) + migrations + withTenantContext, cross-plugin RPC, and the wire-protocol verify surface. One npm package, no -composite/-protocol companions. Self-contained, no kernel internals, no signing capability.",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,13 +16,8 @@
     }
   },
   "files": [
-    "dist",
-    "bin",
-    "src/dev"
+    "dist"
   ],
-  "bin": {
-    "plugin-sdk": "./bin/cli.mjs"
-  },
   "dependencies": {
     "express": "^5.1.0",
     "pg": "^8.16.0",

package/bin/cli.mjs

@@ -1,52 +0,0 @@
-#!/usr/bin/env node
-// @kahitsan/plugin-sdk CLI — the dev toolkit launcher (Vision §5.1, K3/K4).
-//
-//   npx @kahitsan/plugin-sdk <pluginDir> [<pluginDir> …]   ← headline form
-//   npx @kahitsan/plugin-sdk toolkit <pluginDir> …          ← alias (back-compat)
-//
-// Boots the dev-kernel mediator + each plugin on Bun (local SQLite + a synthetic
-// logged-in admin) entirely from the INSTALLED package — no kernel source required.
-// Pass several plugin dirs to exercise the CONTRACT between plugins (does B expose
-// the method A consumes?) locally — no kernel, no Postgres. The harness is Bun-only,
-// so the launcher re-execs under Bun; install it from https://bun.sh.
-import { spawn } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-
-const here = dirname(fileURLToPath(import.meta.url));
-let args = process.argv.slice(2);
-// `toolkit` is an optional leading verb (kept for back-compat); the headline form
-// takes plugin dirs directly, so a global `npx @kahitsan/plugin-sdk ./a ./b` works.
-if (args[0] === "toolkit") args = args.slice(1);
-const wantsHelp = args.includes("-h") || args.includes("--help");
-const dirs = args.filter((a) => !a.startsWith("-"));
-
-if (dirs.length === 0 || wantsHelp) {
-  const out = wantsHelp ? console.log : console.error;
-  out("usage: npx @kahitsan/plugin-sdk <pluginDir> [<pluginDir> …]");
-  out("");
-  out("  Boots the local dev toolkit — a dev-kernel mediator + each plugin on SQLite");
-  out("  + a synthetic logged-in admin, all from this installed package (no kernel");
-  out("  source). Load several plugins at once to exercise their cross-plugin calls:");
-  out("");
-  out("    npx @kahitsan/plugin-sdk ./kplugin_transactions ./kplugin_payees");
-  out("");
-  out("  Requires Bun (https://bun.sh). Ctrl-C stops every plugin.");
-  process.exit(wantsHelp ? 0 : 2);
-}
-
-// The harness ships as Bun source next to the package root (src/dev/), reachable from
-// the published package without any kernel checkout. dev-host.ts takes N plugin dirs.
-const devHost = join(here, "..", "src", "dev", "dev-host.ts");
-const child = spawn("bun", [devHost, ...dirs], { stdio: "inherit" });
-child.on("error", (err) => {
-  if (err && err.code === "ENOENT") {
-    console.error(
-      "The Hilinga plugin toolkit requires Bun (https://bun.sh) — install it and retry.",
-    );
-    process.exit(127);
-  }
-  console.error(err);
-  process.exit(1);
-});
-child.on("exit", (code) => process.exit(code ?? 0));

package/src/dev/dev-assets.ts

@@ -1,156 +0,0 @@
-// Dev-stub asset backend (Phase 5 K3, Vision Data-Arch §8) — the toolkit's stand-in for
-// the kernel's `/_internal/assets/*` endpoints (server/routes/internal-assets.ts). A plugin
-// built with `createPluginServer({ assets: true })` relays `api.assets.{upload,presign,
-// delete}` to KSERP_KERNEL_URL (the dev-kernel) exactly as in prod; this module answers that
-// SAME contract against LOCAL MinIO + an in-memory ledger, clamped to the active view's
-// workspace + owner — so a toolkit dev can upload AND read a file back (the Gate-5 asset
-// requirement) and the ownership clamp behaves like prod (an asset from another workspace/
-// owner is a 404). Bun-only (matches the dev-kernel); never in prod.
-
-import { randomUUID } from "node:crypto";
-
-// The slice of Bun.S3Client this file uses — mirrors packages/plugin-server-utils/src/s3.ts
-// so the dev path stores objects identically to prod, just pointed at local MinIO.
-interface BunS3File {
-  delete(): Promise<number>;
-}
-interface BunS3Client {
-  write(key: string, data: Uint8Array, opts?: { type?: string; acl?: string }): Promise<number>;
-  file(key: string): BunS3File;
-  presign(key: string, opts?: { method?: string; expiresIn?: number }): string;
-}
-interface BunRuntime {
-  S3Client: new (o: {
-    accessKeyId: string;
-    secretAccessKey: string;
-    bucket: string;
-    region: string;
-    endpoint: string;
-  }) => BunS3Client;
-}
-const BUN = (globalThis as { Bun?: BunRuntime }).Bun;
-
-/** A Bun S3 client for local MinIO, or null when S3_* isn't configured (→ 503, like prod). */
-function devS3(): BunS3Client | null {
-  const { S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY } = process.env;
-  if (!BUN || !S3_ENDPOINT || !S3_BUCKET || !S3_ACCESS_KEY || !S3_SECRET_KEY) return null;
-  return new BUN.S3Client({
-    accessKeyId: S3_ACCESS_KEY,
-    secretAccessKey: S3_SECRET_KEY,
-    bucket: S3_BUCKET,
-    region: S3_REGION || "us-east-1",
-    endpoint: new URL(S3_ENDPOINT).origin,
-  });
-}
-
-interface DevAsset {
-  objectKey: string;
-  workspaceId: number;
-  ownerId: string;
-  fileName: string;
-  fileSize: number;
-  mimeType: string;
-}
-// The in-memory equivalent of the prod `kernel_assets` ledger — a single local dev session,
-// so a process-global Map is enough. Cleared on dev-kernel restart (matches "no seeding").
-const ledger = new Map<number, DevAsset>();
-let nextId = 1;
-
-const PRESIGN_TTL_SECONDS = 3600;
-
-function json(body: unknown, status = 200): Response {
-  return Response.json(body, { status });
-}
-
-/** A ledger row, but ONLY if it belongs to the active view's workspace + owner — mirrors
- *  the prod `ownedObjectKey` clamp so a wrong-workspace/owner id is indistinguishable from
- *  absent (404). */
-function owned(
-  assetId: unknown,
-  workspaceId: number,
-  ownerId: string,
-): { id: number; row: DevAsset } | null {
-  const id = Number(assetId);
-  if (!Number.isInteger(id) || id <= 0) return null;
-  const row = ledger.get(id);
-  if (!row || row.workspaceId !== workspaceId || row.ownerId !== ownerId) return null;
-  return { id, row };
-}
-
-interface DevIdentity {
-  workspaceId: number;
-  ownerId: string;
-}
-
-async function doUpload(req: Request, id: DevIdentity, s3: BunS3Client): Promise<Response> {
-  const body = (await req.json().catch(() => ({}))) as {
-    pluginId?: string;
-    fileName?: string;
-    mimeType?: string;
-    data?: string;
-  };
-  const pluginId = String(body.pluginId ?? "");
-  const fileName = String(body.fileName ?? "");
-  const mimeType = String(body.mimeType ?? "");
-  if (!pluginId || !fileName || !mimeType || typeof body.data !== "string") {
-    return json({ error: "pluginId, fileName, mimeType, data required" }, 400);
-  }
-  const buf = Buffer.from(body.data, "base64");
-  // Kernel-built key ({ws}/{plugin}/{rand}), never caller-supplied — a plugin can't write
-  // outside its own prefix, same invariant as prod.
-  const objectKey = `${id.workspaceId}/${pluginId}/${randomUUID()}`;
-  await s3.write(objectKey, new Uint8Array(buf), { type: mimeType, acl: "private" });
-  const assetId = nextId++;
-  ledger.set(assetId, {
-    objectKey,
-    workspaceId: id.workspaceId,
-    ownerId: id.ownerId,
-    fileName,
-    fileSize: buf.length,
-    mimeType,
-  });
-  return json({ id: assetId, objectKey, fileName, fileSize: buf.length, mimeType });
-}
-
-async function doPresign(req: Request, id: DevIdentity, s3: BunS3Client): Promise<Response> {
-  const body = (await req.json().catch(() => ({}))) as { assetId?: number; expirySeconds?: number };
-  const hit = owned(body.assetId, id.workspaceId, id.ownerId);
-  if (!hit) return json({ error: "asset not found" }, 404);
-  const ttl =
-    Number.isInteger(body.expirySeconds) && (body.expirySeconds as number) > 0
-      ? (body.expirySeconds as number)
-      : PRESIGN_TTL_SECONDS;
-  const presignedUrl = s3.presign(hit.row.objectKey, { method: "GET", expiresIn: ttl });
-  const expiresAt = new Date(Date.now() + ttl * 1000).toISOString();
-  return json({ presignedUrl, expiresAt });
-}
-
-async function doDelete(req: Request, id: DevIdentity, s3: BunS3Client): Promise<Response> {
-  const body = (await req.json().catch(() => ({}))) as { assetId?: number };
-  const hit = owned(body.assetId, id.workspaceId, id.ownerId);
-  if (!hit) return json({ error: "asset not found" }, 404);
-  await s3.file(hit.row.objectKey).delete();
-  ledger.delete(hit.id);
-  return json({});
-}
-
-/**
- * Answer the `/_internal/assets/*` contract for the dev-kernel, clamped to the supplied
- * active-view identity. Returns null for a non-asset path (caller falls through to its
- * other routes).
- */
-export async function handleDevAsset(
-  path: string,
-  req: Request,
-  identity: DevIdentity,
-): Promise<Response | null> {
-  if (!path.startsWith("/_internal/assets/")) return null;
-  const s3 = devS3();
-  if (!s3) return json({ error: "asset storage not configured (set S3_* for local MinIO)" }, 503);
-  if (req.method !== "POST") return json({ error: "method not allowed" }, 405);
-
-  if (path === "/_internal/assets/upload") return doUpload(req, identity, s3);
-  if (path === "/_internal/assets/presign") return doPresign(req, identity, s3);
-  if (path === "/_internal/assets/delete") return doDelete(req, identity, s3);
-  return json({ error: "unknown asset endpoint" }, 404);
-}

package/src/dev/dev-host.ts

@@ -1,194 +0,0 @@
-// The dev host (Vision §5.1, K3) — the local environment a plugin developer runs.
-// Boots ONE OR MORE plugins on Bun, each on its own SQLite + synthetic logged-in
-// admin (via the preload), behind a tiny "dev kernel" mediator that stands in for
-// the production kernel's `/_internal/rpc` gateway so cross-plugin calls work — and
-// **degrade gracefully** when a peer isn't loaded (the resilience rule: a missing
-// dependency shows an error, it never crashes the app).
-//
-//   bun packages/plugin-sdk/src/dev/dev-host.ts <pluginDir> [<pluginDir> …]
-//
-// Each plugin's own `server/main.ts` is byte-identical to prod — it just finds the
-// dev hooks installed by the preload and runs on the local engine. Loading several
-// at once lets a developer exercise the CONTRACT between plugins (does B expose the
-// method A consumes?) entirely locally, no kernel, no Postgres.
-
-import { readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { spawn, type Subprocess } from "bun";
-import { handleDevAsset } from "./dev-assets.js";
-
-const DEV_SECRET = "dev-stub-internal-secret";
-const BASE_PORT = Number(process.env.KSERP_DEV_BASE_PORT || "4500");
-const PRELOAD = join(import.meta.dir, "preload.ts");
-
-interface Manifest {
-  name: string;
-  schemas?: string[];
-}
-interface Loaded {
-  dir: string;
-  name: string;
-  port: number;
-  proc: Subprocess;
-  status: "starting" | "up" | "failed";
-}
-
-const dirs = process.argv.slice(2).map((d) => resolve(d));
-if (dirs.length === 0) {
-  console.error("usage: bun dev-host.ts <pluginDir> [<pluginDir> …]");
-  process.exit(1);
-}
-
-// ── assign ports + read manifests (the mediator routes by plugin name → port) ──
-const mediatorPort = BASE_PORT;
-const registry = new Map<string, number>();
-const loaded: Loaded[] = [];
-dirs.forEach((dir, i) => {
-  const manifest = JSON.parse(readFileSync(join(dir, "plugin.manifest.json"), "utf8")) as Manifest;
-  const port = BASE_PORT + 1 + i;
-  registry.set(manifest.name, port);
-  loaded.push({ dir, name: manifest.name, port, proc: undefined as never, status: "starting" });
-});
-
-// Answer the api.assets relay (`/_internal/assets/*`) against local MinIO + an in-memory
-// ledger, clamped to the active (synthetic) identity the relay forwarded in x-kserp-identity.
-// Returns null for a non-asset path. Extracted from the mediator's fetch to keep that handler
-// within its complexity budget.
-async function tryAssetRelay(pathname: string, req: Request): Promise<Response | null> {
-  if (!pathname.startsWith("/_internal/assets/")) return null;
-  let identity = { workspaceId: 1, ownerId: "dev-admin" };
-  const idHdr = req.headers.get("x-kserp-identity");
-  if (idHdr) {
-    try {
-      const v = JSON.parse(idHdr) as { workspaceId?: number; userId?: string };
-      identity = {
-        workspaceId: Number(v.workspaceId) || 1,
-        ownerId: String(v.userId ?? "dev-admin"),
-      };
-    } catch {
-      /* malformed → fall back to the default synthetic admin */
-    }
-  }
-  return handleDevAsset(pathname, req, identity);
-}
-
-// ── the dev-kernel mediator: stands in for the prod kernel's /_internal/rpc. Routes
-//    a cross-plugin call to the target's /_internal/services/<method>; a peer that
-//    isn't loaded → 503, which the SDK's tryCallPlugin turns into a graceful null and
-//    callPlugin into a thrown error the consumer's route reports (never a crash). ──
-const mediator = Bun.serve({
-  port: mediatorPort,
-  async fetch(req) {
-    const url = new URL(req.url);
-    if (url.pathname === "/_internal/rpc" && req.method === "POST") {
-      const body = (await req.json()) as { target: string; method: string; args: unknown };
-      const targetPort = registry.get(body.target);
-      if (!targetPort) {
-        return Response.json(
-          { error: `plugin "${body.target}" is not loaded in this dev session` },
-          { status: 503 },
-        );
-      }
-      try {
-        const upstream = await fetch(
-          `http://127.0.0.1:${targetPort}/_internal/services/${encodeURIComponent(body.method)}`,
-          {
-            method: "POST",
-            headers: {
-              "content-type": "application/json",
-              "x-kserp-internal": DEV_SECRET,
-              ...(req.headers.get("x-kserp-identity")
-                ? { "x-kserp-identity": req.headers.get("x-kserp-identity")! }
-                : {}),
-            },
-            body: JSON.stringify(body.args ?? {}),
-          },
-        );
-        return new Response(await upstream.text(), {
-          status: upstream.status,
-          headers: { "content-type": "application/json" },
-        });
-      } catch {
-        // target loaded but unreachable (still booting / crashed) → 503 = degrade.
-        return Response.json({ error: `plugin "${body.target}" unreachable` }, { status: 503 });
-      }
-    }
-    // api.assets (A1) in the toolkit: a plugin relays upload/presign/delete here.
-    const asset = await tryAssetRelay(url.pathname, req);
-    if (asset) return asset;
-    if (url.pathname === "/" || url.pathname === "/_dev/status") {
-      return Response.json({
-        mediator: `http://127.0.0.1:${mediatorPort}`,
-        plugins: loaded.map((l) => ({ name: l.name, port: l.port, status: l.status })),
-      });
-    }
-    return new Response("dev-kernel", { status: 404 });
-  },
-});
-
-// ── spawn each plugin (Bun + preload → SQLite + synthetic admin) ──
-for (const l of loaded) {
-  const manifest = JSON.parse(
-    readFileSync(join(l.dir, "plugin.manifest.json"), "utf8"),
-  ) as Manifest;
-  l.proc = spawn({
-    cmd: ["bun", "--preload", PRELOAD, join(l.dir, "server", "main.ts")],
-    cwd: l.dir,
-    env: {
-      ...process.env,
-      KSERP_DEV_PLUGIN_DIR: l.dir,
-      KSERP_DB_ENGINE: "sqlite",
-      KSERP_PLUGIN_PORT: String(l.port),
-      KSERP_PLUGIN_BIND: "127.0.0.1",
-      KSERP_PLUGIN_SCHEMAS: (manifest.schemas ?? []).join(","),
-      KSERP_KERNEL_URL: `http://127.0.0.1:${mediatorPort}`,
-      KSERP_INTERNAL_SECRET: DEV_SECRET,
-    },
-    stdout: "inherit",
-    stderr: "inherit",
-  });
-}
-
-// ── wait for health, report (a plugin whose own boot throws — e.g. a peer-dependent
-//    migration — is reported failed, not fatal to the host) ──
-async function waitHealthy(l: Loaded, timeoutMs = 15000): Promise<void> {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    try {
-      const r = await fetch(`http://127.0.0.1:${l.port}/_internal/health`);
-      if (r.ok) {
-        l.status = "up";
-        return;
-      }
-    } catch {
-      /* not up yet */
-    }
-    if (l.proc.exitCode !== null) {
-      l.status = "failed";
-      return;
-    }
-    await Bun.sleep(300);
-  }
-  l.status = l.proc.exitCode === null ? "up" : "failed";
-}
-
-await Promise.all(loaded.map((l) => waitHealthy(l)));
-
-console.log("\n────────────────────────────────────────────────────────");
-console.log(`  dev kernel   http://127.0.0.1:${mediatorPort}  (cross-plugin RPC mediator)`);
-for (const l of loaded) {
-  const mark = l.status === "up" ? "✓" : "✗";
-  console.log(`  ${mark} ${l.name.padEnd(20)} http://127.0.0.1:${l.port}  [${l.status}]`);
-}
-console.log("────────────────────────────────────────────────────────");
-console.log(
-  `  ${loaded.filter((l) => l.status === "up").length}/${loaded.length} plugins up. Ctrl-C to stop.\n`,
-);
-
-function shutdown() {
-  for (const l of loaded) l.proc.kill();
-  mediator.stop(true);
-  process.exit(0);
-}
-process.on("SIGINT", shutdown);
-process.on("SIGTERM", shutdown);