@kahitsan/plugin-sdk 0.4.0 → 0.4.2-staging.18

package/LICENSE

@@ -0,0 +1,20 @@
+@kahitsan/plugin-sdk — PROPRIETARY & CONFIDENTIAL
+Copyright (c) KahitSan Corp. All rights reserved. Licensed, not sold.
+
+This software is the property of KahitSan Corp. and is provided to authorized
+licensees solely to build, run, and test plugins for the Hilinga ERP platform.
+
+The published runtime (`dist/index.js`) is intentionally OBFUSCATED to protect
+trade secrets. De-obfuscating, decompiling, reverse-engineering, beautifying, or
+reconstructing its source is STRICTLY PROHIBITED by this license and by law,
+including anti-circumvention statutes (e.g. 17 U.S.C. § 1201 / DMCA and
+equivalents).
+
+No part of this package may be copied, modified, redistributed, sublicensed, or
+used to create a competing product without the prior written permission of
+KahitSan Corp. (https://kahitsan.com).
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH
+THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# @kahitsan/plugin-sdk
+
+The author surface + dev toolkit for building [Hilinga](https://www.hilinga.com) ERP plugins —
+build, run, and test a plugin locally against a **kernel-identical dev shell**, with **no kernel
+source required**.
+
+Hilinga is a kernel (`kserp`) plus process-isolated plugins. Each plugin is its own repo with its
+own API routes, UI bundle, Postgres schema, migrations, and pm2 process. This package is the single
+public specifier a plugin author installs: it provides the server bootstrap, the workspace-scoped
+data surface, auth/permission guards, the cross-plugin RPC + wire-protocol verify surface, and a Bun
+dev toolkit that boots your plugin inside the real, kernel-identical app shell.
+
+## Install
+
+```bash
+npm install @kahitsan/plugin-sdk
+```
+
+## The dev toolkit
+
+```bash
+npx @kahitsan/plugin-sdk <pluginDir> [<pluginDir> …]
+```
+
+Boots a dev-kernel mediator + each plugin on [Bun](https://bun.sh) (local SQLite + a synthetic
+logged-in admin) **entirely from the installed package** — no kernel checkout, no Postgres. It also
+serves the prebuilt **kernel-identical host-UI shell** (sidebar, plugin route renderer, the settings
+gear + modal — the real visual app), so you develop against what production actually renders.
+
+Pass several plugin dirs to exercise the **contract between plugins** locally — does B expose the
+method A consumes?
+
+```bash
+npx @kahitsan/plugin-sdk ./kplugin_transactions ./kplugin_payees
+```
+
+Requires [Bun](https://bun.sh). `Ctrl-C` stops every plugin.
+
+## The server surface — `createPluginServer`
+
+`createPluginServer` is the one shared bootstrap. It collapses a plugin's hand-written
+`server/main.ts` (manifest + port + pg pool + migrations + identity verify + RLS tenant context +
+services + routers + listen) into a single call, and is the seam the Express → Bun + WS transport
+cutover moves through. Opt-in capabilities (each gated by the kernel + consent model at runtime):
+
+- `settings` — a plugin's private, workspace-scoped KV store (`ctx.settings`)
+- `assets` — the kernel object store (`ctx.assets`)
+- `kernel` — the kernel-data read channel (`ctx.kernel.workspace.get()`)
+- `plugins` — the mediated inter-plugin call surface (`ctx.plugins.get(peer).call(...)`)
+- `events` — emit a domain event the kernel fans out (`ctx.events.emit(topic, payload)`)
+- `flows` — the §9 node-step flow authoring DSL (`buildFlow`, `defineFlow`), imported from
+  `@kahitsan/plugin-sdk/flow` (a browser-safe subpath with no Node built-ins, for plugin UI bundles)
+
+The package **never** includes `signIdentity` (the identity-forging capability) or any shared
+secret — that is the one genuine package-level boundary, enforced by the build's leak gate.
+
+## Authoring guide
+
+The full new-plugin walkthrough lives in the Hilinga docs: **<https://kdocs.kahitsan.com>**
+(`create-plugin/step-1…6`) and in-app at `/docs/plugins`.
+
+## Publishing (maintainers)
+
+This repo publishes `@kahitsan/plugin-sdk` to public npm **independently of any kernel deploy**,
+and builds with **ZERO live kernel** — no submodule, no `KERNEL_REPO_TOKEN`. The minimal `@ks-erp`
+runtime/type surface the SDK inlines is **vendored** at `src/vendor-kernel/` (regenerate it from a
+kernel checkout with `node sync-vendor.mjs <path-to-kserp>`), and the toolkit host-UI shell source
+lives at `shell-src/` (`kserp/src` built with `KSERP_TOOLKIT=1`; its only kernel coupling is two
+pure nav helpers vendored under `shell-src/kernel/`). `build.mjs` produces a self-contained,
+obfuscated `dist/` and runs the K1/K2 leak gate over both the JS and the `.d.ts`; `npm run
+build:shell` builds the kernel-identical static shell from `shell-src/`. CI is
+`.github/workflows/publish-sdk.yml`.
+
+## License
+
+Proprietary. Copyright (c) KahitSan Corp. All rights reserved. Licensed, not sold.

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-import { Router, Request, RequestHandler, Response as Response$1, NextFunction, Express } from 'express';
-export { Router } from 'express';
+import { MiddlewareHandler, Context, Hono } from 'hono';
 import pg, { QueryResultRow, QueryResult, PoolClient, Pool } from 'pg';
 import { Server } from 'node:http';
 interface PluginDb {
@@ -96,11 +95,11 @@ type AuthProviderDecl = {
     validatePath: string;
 };
 type AuthService = {
-    requireAuth: RequestHandler;
-    requireWorkspace: RequestHandler;
-    requireRole: (...roles: string[]) => RequestHandler;
-    requireWorkspaceRole: (...roles: string[]) => RequestHandler;
-    requirePermission: (...codes: string[]) => RequestHandler;
+    requireAuth: MiddlewareHandler;
+    requireWorkspace: MiddlewareHandler;
+    requireRole: (...roles: string[]) => MiddlewareHandler;
+    requireWorkspaceRole: (...roles: string[]) => MiddlewareHandler;
+    requirePermission: (...codes: string[]) => MiddlewareHandler;
     registerAuthProvider: (provider: AuthProvider) => void;
 };
 type PluginManifest = {
@@ -188,10 +187,10 @@ type PluginInitInput = {
 };
 type AdditionalMount = {
     basePath: string;
-    router: Router;
+    router: unknown;
 };
 type PluginInitOutput = {
-    router?: Router;
+    router?: unknown;
     additionalMounts?: AdditionalMount[];
     dispose?: () => Promise<void> | void;
 };
@@ -231,10 +230,10 @@ interface JobDefinition {
     run: (ctx: JobContext) => Promise<void> | void;
 }
 declare function defineJob(name: string, run: (ctx: JobContext) => Promise<void> | void): JobDefinition;
-declare function requirePermission(...codes: string[]): (req: Request, res: Response$1, next: NextFunction) => void;
-declare function requireAuth(req: Request, res: Response$1, next: NextFunction): void;
-declare function requireWorkspace(req: Request, res: Response$1, next: NextFunction): void;
-declare function parseIdentity(req: Request, _res: Response$1, next: NextFunction): void;
+declare function requirePermission(...codes: string[]): MiddlewareHandler;
+declare const requireAuth: MiddlewareHandler;
+declare const requireWorkspace: MiddlewareHandler;
+declare const parseIdentity: MiddlewareHandler;
 declare const IDENTITY_HEADER = "x-kserp-identity";
 declare const INTERNAL_SECRET_HEADER = "x-kserp-internal";
 declare const PROTOCOL_VERSION = 1;
@@ -268,7 +267,13 @@ declare const IdentityBrand: unique symbol;
 type Identity = ForwardedIdentity & {
     readonly [IdentityBrand]: true;
 };
-declare function readIdentity(req: Request): Identity | null;
+declare function readIdentity(req: Request | {
+    req: {
+        raw: Request;
+    };
+} | {
+    headers: Headers | Record<string, string | string[] | undefined>;
+}): Identity | null;
 interface WhereOpts {
     where?: string;
     params?: readonly unknown[];
@@ -310,7 +315,7 @@ interface TenantContext {
 }
 declare function runWithTenantContext<T>(ctx: TenantContext, fn: () => T): T;
 declare function applyTenantContext(client: PoolClient, ctx?: TenantContext | undefined): Promise<void>;
-declare function withTenantContext(req: Request, _res: Response$1, next: NextFunction): void;
+declare const withTenantContext: MiddlewareHandler;
 type Engine = "postgres" | "sqlite";
 type ColumnKind = "id" | "string" | "text" | "int" | "bigint" | "float" | "decimal" | "boolean" | "timestamp" | "date" | "json" | "enum";
 type ColumnDefault = "now" | string | number | boolean | null;
@@ -405,9 +410,9 @@ interface MigrationOpts {
     useTransaction?: boolean;
 }
 declare function migration(name: string, up: (db: MigrationBuilder) => Promise<void>, opts?: MigrationOpts): Migration;
-declare function asyncHandler(fn: (req: Request, res: Response$1, next: NextFunction) => unknown | Promise<unknown>): RequestHandler;
+declare function asyncHandler(fn: (c: Context) => unknown | Promise<unknown>): MiddlewareHandler;
 declare function escapeLike(s: string): string;
-declare function checkProtocol(min?: number, max?: number): (req: Request, res: Response$1, next: NextFunction) => void;
+declare function checkProtocol(min?: number, max?: number): MiddlewareHandler;
 type ResourceColumns = Readonly<Record<string, ColumnDef>>;
 type IndexMember = string | {
     readonly ci: string;
@@ -555,13 +560,13 @@ declare function resourceMigrations(resource: DefinedResource): Migration[];
 type DbHandle = Parameters<typeof makeDataSurface>[0];
 interface ResourceRouterDeps {
     db: DbHandle;
-    requireAuth: RequestHandler;
-    requireWorkspace: RequestHandler;
-    requirePermission?: (...codes: string[]) => RequestHandler;
+    requireAuth: MiddlewareHandler;
+    requireWorkspace: MiddlewareHandler;
+    requirePermission?: (...codes: string[]) => MiddlewareHandler;
 }
-declare function buildResourceRouter(resource: DefinedResource, deps: ResourceRouterDeps): Router;
+declare function buildResourceRouter(resource: DefinedResource, deps: ResourceRouterDeps): Hono;
 type ServiceHandler$1 = (args: unknown, ctx: {
-    req: Request;
+    req: unknown;
 }) => Promise<Array<Record<string, unknown>>>;
 declare function buildResourceServices(resource: DefinedResource, deps: {
     db: DbHandle;
@@ -578,12 +583,14 @@ declare function tryCallPlugin<T = unknown>(target: string, method: string, args
     identityHeader?: string;
     sourcePlugin?: string;
 }): Promise<T | null>;
-declare function identityHeaderOf(req: Request): string | undefined;
+declare function identityHeaderOf(req: Request | Context | {
+    headers: Headers | Record<string, string | string[] | undefined>;
+}): string | undefined;
 type ServiceHandler = (args: unknown, ctx: {
-    req: Request;
+    req: unknown;
 }) => Promise<unknown> | unknown;
-declare function mountPluginServices(app: Express, handlers: Record<string, ServiceHandler>, opts: {
-    parseIdentity: RequestHandler;
+declare function mountPluginServices(app: Hono, handlers: Record<string, ServiceHandler>, opts: {
+    parseIdentity: MiddlewareHandler;
 }): void;
 interface PluginSettings {
     get<T = unknown>(key: string): Promise<T | undefined>;
@@ -664,7 +671,7 @@ interface PluginServerContext {
     plugins?: PluginRpc;
     events?: PluginEvents;
 }
-type PluginRouterFactory = (ctx: PluginServerContext) => Router;
+type PluginRouterFactory = (ctx: PluginServerContext) => Hono;
 type PluginServicesFactory = (ctx: PluginServerContext) => Record<string, ServiceHandler>;
 interface CreatePluginServerOptions {
     importMetaUrl: string;
@@ -678,30 +685,22 @@ interface CreatePluginServerOptions {
     events?: boolean;
     services?: PluginServicesFactory;
     routers?: PluginRouterFactory[];
-    configure?: (app: Express, ctx: PluginServerContext) => void | Promise<void>;
+    configure?: (app: Hono, ctx: PluginServerContext) => void | Promise<void>;
 }
 interface PluginServerHandle {
-    app: Express;
+    app: Hono;
     server: Server;
     ctx?: PluginServerContext;
 }
 declare function createPluginServer(opts: CreatePluginServerOptions): Promise<PluginServerHandle>;
-interface WsSocket {
-    on(event: "message", cb: (data: {
-        toString(): string;
-    }) => void): void;
-    send(data: string): void;
-}
-interface WsServer {
-    on(event: "connection", cb: (socket: WsSocket) => void): void;
-    close(): void;
-}
 interface WsReceiverOptions {
     httpPort: number;
     secret: string;
     host?: string;
 }
-declare function mountWsReceiver(opts: WsReceiverOptions): WsServer | null;
+declare function mountWsReceiver(opts: WsReceiverOptions): {
+    stop: () => void;
+} | null;
 type FlowNodeKind = "data" | "trigger" | "modal" | "load" | "call" | "compute" | "condition" | "commit" | "emit" | "effect" | "terminal";
 interface FlowPort {
     id: string;