@kahitsan/plugin-sdk 0.2.0 → 0.3.0-staging.41

package/src/dev/dev-kernel.ts

@@ -0,0 +1,499 @@
+// The dev-stub TOOLKIT host (Vision §5.1/§5.2): the kernel core in dev mode. It
+// serves the SAME backend contract the REAL host shell calls — so the unmodified
+// vinxi UI renders the plugin in the real Sidebar/PageShell/theme/plugin-renderer —
+// but with the private extensions swapped for dev stubs: auth → a synthetic identity
+// directory (auto-login, no login screen), data → the SQLite dev plugins.
+//
+// The directory ships DEFAULTS a plugin developer can play with immediately — 3 users
+// and 3 workspaces — and a "view-as" control (§5.1) lets them switch the active workspace,
+// user, and role INDEPENDENTLY at runtime (including custom roles they define) to see how
+// their plugin's permission gating responds, with zero login/seeding. The active view is
+// forwarded to each plugin as `x-kserp-dev-identity`, so the role's grants gate the
+// plugin's actions and the workspace scopes its data, live.
+//
+// Run it on the API port the vinxi UI proxies `/api` to; launch the dev plugins
+// separately and pass their registry in KSERP_DEV_PLUGINS. Bun-only. Never in prod.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import sdkPkg from "../../package.json";
+import { handleDevAsset } from "./dev-assets.js";
+
+const SDK_VERSION: string = sdkPkg.version;
+
+interface DevPlugin {
+  name: string;
+  port: number;
+  basePath: string;
+  uiRouteBase: string;
+  label: string;
+  version: string;
+  nav: unknown;
+  /** The plugin's declared permission keys (from its manifest) — drives role gating. */
+  permissions: string[];
+}
+
+const PORT = Number(process.env.KSERP_DEV_KERNEL_PORT || process.env.API_PORT || "4061");
+// The shared internal secret for cross-plugin RPC: plugins verify the inbound
+// `x-kserp-internal` header against their KSERP_INTERNAL_SECRET, so the dev-kernel must
+// forward the SAME value the plugins were launched with (else peer calls are Forbidden).
+const INTERNAL_SECRET = process.env.KSERP_INTERNAL_SECRET || "dev-stub-internal-secret";
+// Cache-bust the remote bundles per dev-kernel boot: prod versions the URL, but in dev
+// the URL is stable and the browser would otherwise serve a stale remote.js (e.g. one
+// cached while a port was briefly mapped to the wrong plugin). New boot → fresh fetch.
+const BOOT_NONCE = String(process.env.KSERP_DEV_BOOT_NONCE || Date.now());
+
+// The registry only needs each plugin's `dir` (+ the `port` it's served on); EVERYTHING
+// else — name, routes, nav, and especially the PERMISSIONS the custom-role builder offers
+// — is read live from that plugin's `plugin.manifest.json`, so the toolkit always reflects
+// the actual plugin. Explicit registry fields still override (for a plugin without a dir).
+interface DevPluginInput extends Partial<DevPlugin> {
+  dir?: string;
+}
+function loadPlugins(): DevPlugin[] {
+  const input: DevPluginInput[] = JSON.parse(process.env.KSERP_DEV_PLUGINS || "[]");
+  return input.map((p) => {
+    let m: Partial<DevPlugin> = {};
+    if (p.dir) {
+      try {
+        m = JSON.parse(
+          readFileSync(join(p.dir, "plugin.manifest.json"), "utf8"),
+        ) as Partial<DevPlugin>;
+      } catch {
+        console.warn(`[dev-kernel] could not read manifest at ${p.dir}/plugin.manifest.json`);
+      }
+    }
+    const name = p.name ?? m.name ?? "plugin";
+    return {
+      name,
+      port: Number(p.port),
+      basePath: p.basePath ?? m.basePath ?? `/api/${name}`,
+      uiRouteBase: p.uiRouteBase ?? m.uiRouteBase ?? name,
+      label: p.label ?? m.label ?? name,
+      version: p.version ?? m.version ?? "0.0.0",
+      nav: p.nav ?? m.nav ?? null,
+      permissions: p.permissions ?? m.permissions ?? [],
+    };
+  });
+}
+const PLUGINS: DevPlugin[] = loadPlugins();
+
+// ── the synthetic identity directory (the auth extension, stubbed) ──
+// A plugin developer builds for WORKSPACES, so the toolkit exposes ONLY workspace roles —
+// never the confidential platform roles (superuser/member). The baseline is workspace
+// "admin"; there's a read-only "viewer"; and the dev can CREATE custom roles at runtime
+// (granting a chosen subset of the plugin's permissions), exactly like a real workspace
+// defining "accountant"/"staff". Workspace, user, and role are INDEPENDENT dimensions the
+// dev switches freely (a dev affordance — not something a real workspace-admin could do).
+interface DevUser {
+  id: string;
+  name: string;
+  email: string;
+}
+interface DevWorkspace {
+  id: number;
+  name: string;
+  slug: string;
+}
+
+const USERS: readonly DevUser[] = [
+  { id: "dev-user-1", name: "Alex Santos", email: "alex@localhost" },
+  { id: "dev-user-2", name: "Bea Cruz", email: "bea@localhost" },
+  { id: "dev-user-3", name: "Caloy Reyes", email: "caloy@localhost" },
+];
+const WORKSPACES: readonly DevWorkspace[] = [
+  { id: 1, name: "Acme Trading", slug: "acme" },
+  { id: 2, name: "Sunrise Cafe", slug: "sunrise" },
+  { id: 3, name: "Metro Hardware", slug: "metro" },
+];
+// Built-in workspace roles. "admin" has full access (bypass); "viewer" is read-only.
+const BUILTIN_ROLES = ["admin", "viewer"];
+// Custom roles the dev creates at runtime: name → the plugin permissions it grants.
+const customRoles: { name: string; permissions: string[] }[] = [];
+const roleNames = (): string[] => [...BUILTIN_ROLES, ...customRoles.map((r) => r.name)];
+
+// The active "view-as" selection — workspace, user, and role are INDEPENDENT (switching
+// one never resets the others). Mutated by POST /api/_dev/view-as, read by every shell
+// endpoint + forwarded to plugins. Process-global (a single local dev session).
+const view = { workspaceId: WORKSPACES[0].id, userId: USERS[0].id, role: "admin" };
+const currentUser = (): DevUser => USERS.find((u) => u.id === view.userId) ?? USERS[0];
+const currentWorkspace = (): DevWorkspace =>
+  WORKSPACES.find((w) => w.id === view.workspaceId) ?? WORKSPACES[0];
+
+// The plugin permissions a custom role can grant (and the read-ish subset "viewer" gets).
+const allPluginPermissions = (): string[] => [
+  ...new Set(PLUGINS.flatMap((p) => p.permissions ?? [])),
+];
+const READ_PERM = /(?:^|[._-])(view|read|list|get|show|index|export)(?:$|[._-])/i;
+const DESTRUCTIVE_PERM = /(?:^|[._-])(delete|remove|destroy|purge|archive)(?:$|[._-])/i;
+// Per-role grant overrides edited live via the Share matrix (PUT /role-permissions). An
+// override REPLACES the role's computed default, so a matrix edit drives the plugin's gating
+// immediately — the dev customizes a role and watches the plugin respond, like a real ws.
+const roleGrantOverrides = new Map<string, Set<string>>();
+
+function grantsForRoleDefault(role: string): { bypass: boolean; permissions: string[] } {
+  if (role === "admin") return { bypass: true, permissions: [] };
+  if (role === "viewer")
+    return { bypass: false, permissions: allPluginPermissions().filter((k) => READ_PERM.test(k)) };
+  const custom = customRoles.find((r) => r.name === role);
+  return { bypass: false, permissions: custom ? custom.permissions : [] };
+}
+
+// The role's effective permission set as the Share matrix shows it (override wins; admin's
+// bypass expands to "everything checked").
+function effectivePermSet(role: string): Set<string> {
+  const ov = roleGrantOverrides.get(role);
+  if (ov) return ov;
+  const g = grantsForRoleDefault(role);
+  return new Set(g.bypass ? allPluginPermissions() : g.permissions);
+}
+
+function grantsForRole(role: string): { bypass: boolean; permissions: string[] } {
+  if (roleGrantOverrides.has(role))
+    return { bypass: false, permissions: [...effectivePermSet(role)] };
+  return grantsForRoleDefault(role);
+}
+
+// The kernel's role→permission matrix contract — what the gear's PluginSettingsModal "Share"
+// tab reads (GET) and writes (PUT). The SAME shape the real host serves, so the UNMODIFIED
+// kernel modal works in the toolkit: customize a role's grants and the plugin's gating follows.
+function rolePermissionsResponse() {
+  const roles = roleNames().map((code, i) => ({
+    code,
+    label: code.charAt(0).toUpperCase() + code.slice(1),
+    description: null,
+    sort_order: i,
+  }));
+  const permissions = allPluginPermissions().map((code, i) => {
+    const [module, action = ""] = code.split(".");
+    return {
+      code,
+      module,
+      action,
+      label: action ? action.charAt(0).toUpperCase() + action.slice(1) : code,
+      description: null,
+      sort_order: i,
+      is_destructive: DESTRUCTIVE_PERM.test(code),
+    };
+  });
+  const grants: { role_code: string; permission_code: string; allowed: boolean }[] = [];
+  for (const r of roles) {
+    const eff = effectivePermSet(r.code);
+    for (const p of permissions)
+      grants.push({ role_code: r.code, permission_code: p.code, allowed: eff.has(p.code) });
+  }
+  return { workspace_id: view.workspaceId, roles, permissions, grants };
+}
+
+async function handleRolePermissions(req: Request): Promise<Response> {
+  if (req.method === "GET") return json(rolePermissionsResponse());
+  if (req.method === "PUT") {
+    const body = (await req.json().catch(() => ({}))) as {
+      grants?: { role_code: string; permission_code: string; allowed: boolean }[];
+    };
+    for (const g of body.grants ?? []) {
+      let ov = roleGrantOverrides.get(g.role_code);
+      if (!ov) {
+        ov = new Set(effectivePermSet(g.role_code)); // seed from current effective, then edit
+        roleGrantOverrides.set(g.role_code, ov);
+      }
+      if (g.allowed) ov.add(g.permission_code);
+      else ov.delete(g.permission_code);
+    }
+    return json({ ok: true });
+  }
+  return json({ error: "method not allowed" }, 405);
+}
+
+function json(body: unknown, status = 200): Response {
+  return Response.json(body, { status });
+}
+
+function meResponse() {
+  const u = currentUser();
+  const w = currentWorkspace();
+  // The dev is always a regular platform user (never the confidential superuser); the
+  // active workspace role is whatever they selected. All 3 workspaces are listed so the
+  // existing switcher dropdown can move between them.
+  const workspaces = WORKSPACES.map((ws) => ({
+    ws_id: ws.id,
+    ws_name: ws.name,
+    ws_slug: ws.slug,
+    ws_role: view.role,
+  }));
+  return {
+    // username set so the prod "pick a username" banner stays out of the toolkit.
+    user: { id: u.id, name: u.name, email: u.email, role: "user", is_active: true, username: u.id },
+    workspaces,
+    workspace: { ws_id: w.id, ws_name: w.name, ws_slug: w.slug, ws_role: view.role },
+    // devMode + sdkVersion tell the host shell it's the toolkit: strip the prod chrome,
+    // show the SDK build, swap the dev (blue) icon (§5.1).
+    devMode: true,
+    sdkVersion: SDK_VERSION,
+    sdkPackage: sdkPkg.name,
+  };
+}
+
+function permissionsResponse() {
+  // Role-driven so the dev can test role-sensitive permissions: switching the active role
+  // changes exactly which of the plugin's permission-gated actions show. Never superuser.
+  const { bypass, permissions } = grantsForRole(view.role);
+  return {
+    permissions,
+    effectivePermissions: permissions,
+    bypass,
+    isSuperUser: false,
+    isAdmin: view.role === "admin",
+  };
+}
+
+/** The active view, as the header the prod kernel would sign — the plugin's dev
+ *  middleware reads it so the active role scopes the plugin per-request. */
+function devIdentityHeader(): string {
+  const u = currentUser();
+  return JSON.stringify({
+    userId: u.id,
+    workspaceId: view.workspaceId,
+    role: "user",
+    wsRole: view.role,
+    name: u.name,
+    email: u.email,
+  });
+}
+
+async function proxyToPlugin(p: DevPlugin, path: string, req: Request): Promise<Response> {
+  try {
+    const headers = new Headers(req.headers);
+    headers.set("x-kserp-dev-identity", devIdentityHeader());
+    const upstream = await fetch(`http://127.0.0.1:${p.port}${path}`, {
+      method: req.method,
+      headers,
+      body: req.method === "GET" || req.method === "HEAD" ? undefined : await req.text(),
+    });
+    return new Response(upstream.body, { status: upstream.status, headers: upstream.headers });
+  } catch {
+    // A peer/plugin that's down degrades to a 503 the UI shows — never crashes.
+    return json({ error: `plugin "${p.name}" unreachable` }, 503);
+  }
+}
+
+// The plugin-ui envelope the real PluginUiProvider expects.
+function pluginsUi() {
+  return {
+    plugins: PLUGINS.map((p) => ({
+      name: p.name,
+      basePath: p.basePath,
+      uiRouteBase: p.uiRouteBase,
+      // The plugin renderer matches the URL's first segment against p.routeBase; the
+      // Sidebar links to p.href.
+      routeBase: p.uiRouteBase,
+      href: `/${p.uiRouteBase}`,
+      label: p.label,
+      version: p.version,
+      // The host loads this remote bundle; we proxy it to the plugin's own /_ui.
+      // ?v=<boot> busts any stale browser-cached bundle from a prior dev session.
+      remoteEntry: `${p.basePath}/_ui/remote.js?v=${BOOT_NONCE}`,
+      // The plugin's view permission — gates the nav row (a role without it hides the row,
+      // so gating is visible live) AND lets the sidebar resolve the plugin "module" so the
+      // per-row dev settings gear renders (navModuleOf needs a requiredPermission).
+      navPermission:
+        (p.permissions ?? []).find((perm) => perm === `${p.uiRouteBase}.view`) ??
+        (p.permissions ?? []).find((perm) => perm.endsWith(".view")) ??
+        `${p.uiRouteBase}.view`,
+      nav: p.nav ?? { label: p.label, section: "plugins", icon: "box" },
+    })),
+    routeSettings: {},
+    theme: {},
+  };
+}
+
+/** Shell read-channels + the dev-control endpoints, all reflecting the active view.
+ *  Returns null for a path this doesn't own (caller then tries RPC / the plugin proxy). */
+function shellEndpoint(path: string): Response | null {
+  if (path === "/api/auth/get-session" || path.startsWith("/api/auth/")) {
+    const u = currentUser();
+    // The dev is always a regular platform user (never the confidential superuser).
+    return json({
+      user: { id: u.id, name: u.name, email: u.email, role: "user", username: u.id },
+      session: { userId: u.id },
+    });
+  }
+  if (path === "/api/me") return json(meResponse());
+  if (path === "/api/capabilities") return json({ capabilities: {} });
+  if (path === "/api/permissions/me") return json(permissionsResponse());
+  if (path === "/api/permissions") return json({ permissions: [] });
+  if (path === "/api/plugins/ui") return json(pluginsUi());
+  if (path === "/api/plugins/ui/nav-config") return json({ navConfig: null });
+  if (path.startsWith("/api/plugins/ui/route-settings")) return json({});
+  if (path === "/api/theme/me" || path === "/api/theme/workspace-default") return json({});
+  // The view-as directory the dev controls read (users + roles + the plugin permissions
+  // a custom role can grant).
+  if (path === "/api/_dev/info")
+    return json({
+      sdkVersion: SDK_VERSION,
+      sdkPackage: sdkPkg.name,
+      pluginPermissions: allPluginPermissions(),
+      // Per-plugin permissions + route segment, so the toolkit can scope the role
+      // builder to the plugin whose page the dev is on (route-aware permission tuning)
+      // and link straight to that plugin's §9 flow (`/<routeBase>.spec`).
+      plugins: PLUGINS.map((p) => ({
+        name: p.name,
+        routeBase: p.uiRouteBase,
+        permissions: p.permissions ?? [],
+      })),
+      roles: roleNames(),
+      builtinRoles: BUILTIN_ROLES,
+      customRoles,
+      users: USERS,
+      workspaces: WORKSPACES,
+      view,
+    });
+  return null;
+}
+
+async function handleViewAs(req: Request): Promise<Response> {
+  const body = (await req.json().catch(() => ({}))) as {
+    userId?: string;
+    role?: string;
+    workspaceId?: number;
+  };
+  // Workspace, user, and role are INDEPENDENT — setting one never resets the others.
+  if (body.workspaceId && WORKSPACES.some((w) => w.id === body.workspaceId))
+    view.workspaceId = body.workspaceId;
+  if (body.userId && USERS.some((u) => u.id === body.userId)) view.userId = body.userId;
+  if (body.role && roleNames().includes(body.role)) view.role = body.role;
+  return json({ ok: true, view });
+}
+
+// Create (or update) a custom workspace role from a chosen subset of the loaded plugins'
+// permissions — the toolkit equivalent of a workspace defining "accountant"/"staff" — and
+// make it the active role so the dev immediately sees its gating.
+async function handleCreateRole(req: Request): Promise<Response> {
+  const body = (await req.json().catch(() => ({}))) as { name?: string; permissions?: string[] };
+  const name = String(body.name ?? "")
+    .trim()
+    .toLowerCase();
+  if (!name || BUILTIN_ROLES.includes(name))
+    return json({ error: "invalid or reserved role name" }, 400);
+  const valid = allPluginPermissions();
+  const permissions = (Array.isArray(body.permissions) ? body.permissions : []).filter((p) =>
+    valid.includes(p),
+  );
+  const existing = customRoles.find((r) => r.name === name);
+  if (existing) existing.permissions = permissions;
+  else customRoles.push({ name, permissions });
+  view.role = name;
+  return json({ ok: true, roles: roleNames(), view });
+}
+
+/** /api/plugins/graph for the toolkit — each dev plugin as a node, with the §9
+ *  flows it declares (fetched from its /__meta/flows). Falls back gracefully to an
+ *  empty `flows` (the host then derives a flow from `permissions`). */
+async function pluginsGraph(): Promise<Response> {
+  const plugins = await Promise.all(
+    PLUGINS.map(async (p) => {
+      let flows: unknown[] = [];
+      try {
+        const r = await fetch(`http://127.0.0.1:${p.port}/__meta/flows`, {
+          signal: AbortSignal.timeout(800),
+        });
+        if (r.ok) {
+          const body = (await r.json()) as unknown;
+          if (Array.isArray(body)) flows = body;
+        }
+      } catch {
+        // plugin not serving flows (older SDK) — empty → permission-derived fallback
+      }
+      return {
+        name: p.name,
+        key: p.uiRouteBase,
+        label: p.label,
+        tier: null,
+        emits: [],
+        permissions: p.permissions,
+        flows,
+      };
+    }),
+  );
+  return json({ plugins, edges: [] });
+}
+
+async function handleRpc(req: Request): Promise<Response> {
+  const body = (await req.json()) as { target: string; method: string; args: unknown };
+  const target = PLUGINS.find((x) => x.name === body.target);
+  if (!target)
+    return json({ error: `plugin "${body.target}" is not loaded in this dev session` }, 503);
+  return proxyToPlugin(
+    target,
+    `/_internal/services/${encodeURIComponent(body.method)}`,
+    new Request(req.url, {
+      method: "POST",
+      headers: { "content-type": "application/json", "x-kserp-internal": INTERNAL_SECRET },
+      body: JSON.stringify(body.args ?? {}),
+    }),
+  );
+}
+
+// The dev-control + kernel-contract routes the view-as / settings-modal UI calls. Returns
+// null when `path` isn't one, so the main handler falls through to the shell stub / proxy.
+function handleControlRoute(path: string, req: Request): Response | Promise<Response> | null {
+  if (path === "/api/_dev/view-as" && req.method === "POST") return handleViewAs(req);
+  if (path === "/api/_dev/roles" && req.method === "POST") return handleCreateRole(req);
+  // The settings-modal flow graph: the dev plugins as nodes + the §9 flows each serves at
+  // /__meta/flows, so an author previews their declared flow in the toolkit as in prod.
+  if (path === "/api/plugins/graph") return pluginsGraph();
+  // The Share tab's role→permission matrix (GET) + live edits (PUT). `:id` is the active
+  // workspace; the dev session is single-workspace so the id is informational.
+  if (/^\/api\/workspaces\/[^/]+\/role-permissions$/.test(path)) return handleRolePermissions(req);
+  return null;
+}
+
+Bun.serve({
+  port: PORT,
+  idleTimeout: 30,
+  async fetch(req) {
+    const url = new URL(req.url);
+    const path = url.pathname;
+
+    const ctrl = handleControlRoute(path, req);
+    if (ctrl) return ctrl;
+
+    const stub = shellEndpoint(path);
+    if (stub) return stub;
+
+    // ── cross-plugin RPC mediation (IP1): an unloaded peer → 503, which the SDK's
+    //    tryCallPlugin degrades to null (the contract a dev can test between plugins). ──
+    if (path === "/_internal/rpc" && req.method === "POST") return handleRpc(req);
+
+    // ── api.assets (A1) in the toolkit: a dev plugin relays upload/presign/delete here;
+    //    answered against local MinIO + an in-memory ledger, clamped to the active view's
+    //    workspace + owner (the dev equivalent of the prod token clamp). ──
+    if (path.startsWith("/_internal/assets/")) {
+      const r = await handleDevAsset(path, req, {
+        workspaceId: view.workspaceId,
+        ownerId: view.userId,
+      });
+      if (r) return r;
+    }
+
+    // ── plugin proxy: <basePath>/* (incl. the /_ui bundle) → the dev plugin. Match by
+    //    basePath, NOT by name — a plugin's basePath segment need not equal its name
+    //    (e.g. the timesheets plugin serves `/api/time-entries`), so matching the first
+    //    path segment against the name silently 404s those plugins' bundles + routes. ──
+    if (path.startsWith("/api/")) {
+      const p = PLUGINS.find((x) => path === x.basePath || path.startsWith(x.basePath + "/"));
+      if (p) {
+        const rest = path.slice(p.basePath.length);
+        return proxyToPlugin(p, (rest || "/") + url.search, req);
+      }
+    }
+
+    // Unknown API call → empty 200 (a missing read-channel must not break the shell).
+    if (path.startsWith("/api/")) return json({});
+    return new Response("dev-kernel (toolkit mode)", { status: 404 });
+  },
+});
+
+console.log(
+  `[dev-kernel] toolkit mode on :${PORT} — ${sdkPkg.name}@${SDK_VERSION}, ${USERS.length} users, ${WORKSPACES.length} workspaces, ${BUILTIN_ROLES.length}+ roles, ${PLUGINS.length} plugin(s): ${PLUGINS.map((p) => p.name).join(", ")}`,
+);

package/src/dev/preload.ts

@@ -0,0 +1,61 @@
+// Dev-host Bun PRELOAD (Vision §5.1). Runs before a plugin's `server/main.ts` in a
+// `bun --preload` launch and installs the two dev hooks `createPluginServer` reads:
+//
+//   • a bun:sqlite pool (the local engine — Postgres in prod, SQLite in dev), and
+//   • a synthetic logged-in admin (auto-login: no kernel, no signed token).
+//
+// The plugin's own code is byte-identical — it just calls `createPluginServer(...)`
+// and, finding `globalThis.__KSERP_DEV__` set, runs on SQLite as the synthetic admin.
+// Bun-only (imports bun:sqlite); never on the prod path.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { makeSqlitePool } from "./sqlite-pool.js";
+
+const pluginDir = process.env.KSERP_DEV_PLUGIN_DIR;
+if (!pluginDir) {
+  throw new Error("[dev-stub] KSERP_DEV_PLUGIN_DIR not set (the preload needs the plugin root)");
+}
+
+// Read the manifest so the synthetic admin is granted exactly this plugin's declared
+// permissions — so `requirePermission('<key>.view'|…)` passes for every route the
+// plugin gates, without a real role/grant table.
+interface Manifest {
+  name: string;
+  permissions?: string[];
+  schemas?: string[];
+}
+const manifest = JSON.parse(
+  readFileSync(join(pluginDir, "plugin.manifest.json"), "utf8"),
+) as Manifest;
+
+// One SQLite file per plugin (mirrors prod's schema-per-plugin isolation; cross-plugin
+// reads go over the mediated RPC, never a shared DB). In-memory unless a dir is given.
+const sqliteFile = process.env.KSERP_SQLITE_FILE || ":memory:";
+
+const workspaceId = Number(process.env.KSERP_DEV_WORKSPACE_ID || "1");
+const userId = "dev-admin";
+
+(globalThis as { __KSERP_DEV__?: unknown }).__KSERP_DEV__ = {
+  poolFactory: () =>
+    makeSqlitePool(
+      sqliteFile,
+      { workspaceId, userId, wsRole: "Admin", userName: "Dev Admin" },
+      manifest.schemas ?? [],
+    ),
+  identity: {
+    userId,
+    workspaceId,
+    role: "superuser",
+    wsRole: "Admin",
+    // The dev admin can do everything THIS plugin declares.
+    permissions: manifest.permissions ?? [],
+    email: "dev@localhost",
+    name: "Dev Admin",
+  },
+};
+
+console.log(
+  `[dev-stub] ${manifest.name}: bun:sqlite (${sqliteFile}) + synthetic admin ` +
+    `(${(manifest.permissions ?? []).length} perms) installed`,
+);