@kahitsan/plugin-sdk 0.4.0 → 0.4.2

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.