@kahitsan/plugin-sdk

The author surface + dev toolkit for building Hilinga 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

npm install @kahitsan/plugin-sdk

The dev toolkit

npx @kahitsan/plugin-sdk <pluginDir> [<pluginDir> …]

Boots a dev-kernel mediator + each plugin on Bun (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?

npx @kahitsan/plugin-sdk ./kplugin_transactions ./kplugin_payees

Requires Bun. 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.