@stina/extension-api 0.6.5 → 0.7.1
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 +107 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# @stina/extension-api
|
|
2
|
+
|
|
3
|
+
Type definitions and runtime helpers for building extensions for Stina (https://github.com/einord/stina).
|
|
4
|
+
Use this package to define your extension manifest, register tools/providers, and access the extension context.
|
|
5
|
+
|
|
6
|
+
## What this package is for
|
|
7
|
+
|
|
8
|
+
- Authoring Stina extensions (tools, providers, settings, commands, prompts).
|
|
9
|
+
- Typing `manifest.json` and runtime code with Stina's Extension API.
|
|
10
|
+
- Running extension code inside Stina's sandboxed worker via the runtime helper.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
pnpm add @stina/extension-api
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
(Use npm or yarn if you prefer.)
|
|
19
|
+
|
|
20
|
+
## Minimal extension example
|
|
21
|
+
|
|
22
|
+
### 1) `manifest.json`
|
|
23
|
+
|
|
24
|
+
```json
|
|
25
|
+
{
|
|
26
|
+
"id": "example.hello",
|
|
27
|
+
"name": "Hello Extension",
|
|
28
|
+
"version": "0.1.0",
|
|
29
|
+
"description": "Adds a hello tool",
|
|
30
|
+
"author": { "name": "Your Name" },
|
|
31
|
+
"main": "dist/index.js",
|
|
32
|
+
"permissions": ["tools.register"],
|
|
33
|
+
"contributes": {
|
|
34
|
+
"tools": [
|
|
35
|
+
{
|
|
36
|
+
"id": "example.hello",
|
|
37
|
+
"name": "Hello",
|
|
38
|
+
"description": "Returns a friendly greeting",
|
|
39
|
+
"parameters": {
|
|
40
|
+
"type": "object",
|
|
41
|
+
"properties": {
|
|
42
|
+
"name": { "type": "string" }
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
]
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### 2) Extension entry point (`src/index.ts`)
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
import type { ExtensionModule } from '@stina/extension-api'
|
|
55
|
+
import { initializeExtension } from '@stina/extension-api/runtime'
|
|
56
|
+
|
|
57
|
+
const extension: ExtensionModule = {
|
|
58
|
+
activate(context) {
|
|
59
|
+
context.log.info('Hello extension activated', { id: context.extension.id })
|
|
60
|
+
|
|
61
|
+
context.tools?.register({
|
|
62
|
+
id: 'example.hello',
|
|
63
|
+
name: 'Hello',
|
|
64
|
+
description: 'Returns a friendly greeting',
|
|
65
|
+
execute: async (params) => {
|
|
66
|
+
const name = typeof params?.name === 'string' ? params.name : 'there'
|
|
67
|
+
return { message: `Hello, ${name}!` }
|
|
68
|
+
},
|
|
69
|
+
})
|
|
70
|
+
},
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
initializeExtension(extension)
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### 3) Build output
|
|
77
|
+
|
|
78
|
+
Bundle your extension so that `manifest.json` points at the built file (`main`).
|
|
79
|
+
For example, compile to `dist/index.js` and publish the zip/release with:
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
manifest.json
|
|
83
|
+
src/
|
|
84
|
+
dist/
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Common patterns
|
|
88
|
+
|
|
89
|
+
- Use `contributes` in `manifest.json` for UI definitions.
|
|
90
|
+
- Use `context.tools?.register(...)` or `context.providers?.register(...)` at runtime.
|
|
91
|
+
- Always include the permission that matches what you register (`tools.register`, `provider.register`, etc.).
|
|
92
|
+
- Keep runtime code platform-agnostic; it runs in a worker.
|
|
93
|
+
|
|
94
|
+
## Publish to Stina Extension Library
|
|
95
|
+
|
|
96
|
+
Extensions that should appear in the Stina Extension Library must be registered via a Pull Request to:
|
|
97
|
+
https://github.com/einord/stina-extensions-registry
|
|
98
|
+
|
|
99
|
+
## Real-world example
|
|
100
|
+
|
|
101
|
+
For a real, but still approachable example of a Stina extension in use, see:
|
|
102
|
+
https://github.com/einord/stina-ext-people
|
|
103
|
+
|
|
104
|
+
## Links
|
|
105
|
+
|
|
106
|
+
- Manifest types: `ExtensionManifest` in this package.
|
|
107
|
+
- Runtime helper: `@stina/extension-api/runtime`.
|