@kdlbs/plugin-sdk 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,69 @@
1
- # Temporary Holding Version
1
+ # @kdlbs/plugin-sdk
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Runtime-free TypeScript contracts for Kandev UI plugins.
4
+
5
+ The shared Go/npm SDK version starts at `0.1.0`, independently of Kandev.
6
+ Public installation is available only after a verified Stable SDK release.
7
+ After that release, install an exact version with
8
+ `npm install --save-dev --save-exact @kdlbs/plugin-sdk@0.1.0` and commit the
9
+ lockfile. Read the exported `@kdlbs/plugin-sdk/sdk-release.json` for the
10
+ originating host, SDK-wide host floor, and supported manifest API versions.
11
+
12
+ Run the Go-hosted compatibility command from the frontend project root:
13
+
14
+ ```bash
15
+ go run github.com/kdlbs/kandev/pluginsdk/cmd/kandev-sdk-check@v0.1.0 \
16
+ --manifest manifest.yaml --frontend-only --frontend-sdk node_modules/@kdlbs/plugin-sdk
17
+ ```
18
+
19
+ The checker supports npm lockfile v2/v3 and pnpm lockfile v9. It rejects local
20
+ SDK links and insufficient host minima. See the
21
+ [authoring guide](https://github.com/kdlbs/kandev/blob/main/docs/public/plugins-authoring.md)
22
+ for combined Go/frontend checks and migration. The package is licensed under
23
+ AGPL-3.0-only; see `LICENSE`.
24
+
25
+ Use `import type` from this package and render with the `host.React`, `host.jsx`,
26
+ and `host.ui` values supplied to `initialize`. The package deliberately has no
27
+ dependency on React and no Zustand or Kandev web-application imports, so an
28
+ external plugin can typecheck from an isolated or sparse checkout without
29
+ inheriting the host's private module graph.
30
+
31
+ Official plugins use `host.context` for typed provider-neutral reads. Do not
32
+ copy `AppState` slice shapes or import files from `apps/web`; extend this package
33
+ and the host context implementation when a reusable capability is missing.
34
+
35
+ The `PluginHostV2*` interfaces describe capability and command data that a
36
+ plugin backend may project into its own UI. They are data types only. Browser
37
+ plugins do not receive the privileged Go Host connection or call backend Host
38
+ RPCs directly. Managed conversation input contracts include durable receipts,
39
+ bounded sequence-cursor reads, exact cancellation, and immediate dispatch
40
+ outcomes. A `busy` immediate-dispatch result never means that the host queued
41
+ the input; use enqueue when the caller needs durable delivery while a turn is
42
+ running. Only periodic inputs may request coalescing with a non-empty key.
43
+
44
+ `PluginHostV2TaskCompletionGateSnapshot` is a bounded projection type for a
45
+ plugin UI. Only the Go Host SDK can call the privileged exact completion
46
+ commands; browser plugins cannot set criteria or evidence directly.
47
+
48
+ The web Host SDK also exposes reusable `WorkspaceAgentChat`,
49
+ `WorkspaceTaskStatus`, and `WorkspaceTaskUsage` components, plus typed
50
+ `host.queries` and `host.interactions` facades. Managed-session recovery is
51
+ available only when the Host reports both the session resource version and the
52
+ opaque execution generation; plugins must pass those observed fences back to
53
+ the exact command and must not infer a recovery target from task state alone.
54
+
55
+ Register an English translation catalog with `registry.registerTranslations`
56
+ and render user-facing copy through `host.i18n`. The host scopes catalogs to the
57
+ plugin, supplies locale fallback and plural interpolation, and removes them with
58
+ the plugin generation.
59
+
60
+ Registration `icon` fields accept a curated host icon name or a plugin-owned
61
+ component. Build custom brand glyphs with `host.jsx`; Kandev renders that component
62
+ through its React runtime on navigation, repository, task-link, settings, and review
63
+ surfaces. This keeps provider assets in the provider repository.
64
+
65
+ Composer slot consumers can import `PluginComposerSlotProps` and the
66
+ `PluginTaskCreatedHandler` types. `registerTaskCreatedHandler` is available only
67
+ on create-mode `task-create-input-actions`; its returned disposer unregisters
68
+ the callback. Task-created callbacks may return a promise and receive a readonly
69
+ `{ id, workspace_id }` identity.
package/package.json CHANGED
@@ -1,6 +1,34 @@
1
1
  {
2
2
  "name": "@kdlbs/plugin-sdk",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "description": "Versioned frontend contracts for Kandev runtime plugins",
5
+ "type": "module",
6
+ "main": "./src/index.ts",
7
+ "types": "./src/index.ts",
8
+ "exports": {
9
+ ".": "./src/index.ts",
10
+ "./sdk-release.json": "./sdk-release.json"
11
+ },
12
+ "files": [
13
+ "src",
14
+ "sdk-release.json",
15
+ "README.md",
16
+ "LICENSE"
17
+ ],
18
+ "publishConfig": {
19
+ "access": "public"
20
+ },
21
+ "scripts": {
22
+ "test": "node --test test/*.node.mjs",
23
+ "typecheck": "tsc --noEmit"
24
+ },
25
+ "devDependencies": {
26
+ "typescript": "^5.7.2"
27
+ },
28
+ "license": "AGPL-3.0-only",
29
+ "repository": {
30
+ "type": "git",
31
+ "url": "git+https://github.com/kdlbs/kandev.git",
32
+ "directory": "apps/packages/plugin-sdk"
33
+ }
34
+ }
@@ -0,0 +1,11 @@
1
+ {
2
+ "schema_version": 1,
3
+ "sdk_version": "0.2.0",
4
+ "host_release": "0.100.0",
5
+ "min_kandev_version": "0.100.0",
6
+ "api_versions": [
7
+ 1,
8
+ 2
9
+ ],
10
+ "change_kind": "additive"
11
+ }