@kition/extensions 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/dist/LICENSE +177 -0
- package/dist/chunks/runtime-BVJHE1Pg.js +997 -0
- package/dist/index.js +438 -0
- package/dist/panel.html +208 -0
- package/dist/runtime.js +198 -0
- package/dist/sandbox.html +35 -0
- package/dist/types/src/gate.d.ts +17 -0
- package/dist/types/src/generated/runtime.d.ts +8 -0
- package/dist/types/src/host.d.ts +135 -0
- package/dist/types/src/index.d.ts +13 -0
- package/dist/types/src/manifest.d.ts +82 -0
- package/dist/types/src/protocol.d.ts +159 -0
- package/dist/types/src/rpc.d.ts +52 -0
- package/dist/types/src/runtime/document.d.ts +40 -0
- package/dist/types/src/runtime/index.d.ts +10 -0
- package/dist/types/src/runtime/panel.d.ts +19 -0
- package/dist/types/src/runtime/runtime.d.ts +54 -0
- package/dist/types/src/runtime/worker.d.ts +1 -0
- package/dist/types/src/sandbox.d.ts +41 -0
- package/package.json +37 -3
- package/README.md +0 -3
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The channel between the host and an extension's worker: requests, answers, and notifications
|
|
3
|
+
* as plain objects over one `MessagePort` (or anything with its `postMessage` and `onmessage`).
|
|
4
|
+
*/
|
|
5
|
+
/** What a `MessagePort` offers that the channel uses; fakes in tests offer the same. */
|
|
6
|
+
export interface PortLike {
|
|
7
|
+
postMessage(message: unknown, transfer?: Transferable[]): void;
|
|
8
|
+
onmessage: {
|
|
9
|
+
bivarianceHack(event: {
|
|
10
|
+
data: unknown;
|
|
11
|
+
ports?: readonly MessagePort[];
|
|
12
|
+
}): void;
|
|
13
|
+
}['bivarianceHack'] | null;
|
|
14
|
+
start?(): void;
|
|
15
|
+
close?(): void;
|
|
16
|
+
}
|
|
17
|
+
/** Every message on the channel carries this tag; anything else is ignored. */
|
|
18
|
+
export declare const CHANNEL_TAG = "kition-ext/1";
|
|
19
|
+
/**
|
|
20
|
+
* An error that crosses the channel. `code` is `permission-denied`, `not-found`, `invalid`,
|
|
21
|
+
* `failed`, or one of the object model's batch codes (`read-only`, `invalid-op`, …).
|
|
22
|
+
*/
|
|
23
|
+
export declare class ExtensionError extends Error {
|
|
24
|
+
readonly code: string;
|
|
25
|
+
readonly data?: Record<string, unknown> | undefined;
|
|
26
|
+
constructor(code: string, message: string, data?: Record<string, unknown> | undefined);
|
|
27
|
+
toJSON(): {
|
|
28
|
+
data?: Record<string, unknown> | undefined;
|
|
29
|
+
code: string;
|
|
30
|
+
message: string;
|
|
31
|
+
};
|
|
32
|
+
}
|
|
33
|
+
/** Answers a request or a notification; `ports` are the `MessagePort`s that came with it. */
|
|
34
|
+
export type Handler = (params: never, ports: readonly MessagePort[]) => unknown;
|
|
35
|
+
/** One end of the channel. */
|
|
36
|
+
export declare class RpcPeer {
|
|
37
|
+
private readonly port;
|
|
38
|
+
private next;
|
|
39
|
+
private pending;
|
|
40
|
+
private handlers;
|
|
41
|
+
private closed;
|
|
42
|
+
constructor(port: PortLike);
|
|
43
|
+
/** Answers `method` with `handler` (its result, or the error it throws). */
|
|
44
|
+
handle(method: string, handler: Handler): this;
|
|
45
|
+
/** Asks `method`; `transfer` (a `MessagePort`, …) goes with the request. */
|
|
46
|
+
request<T = unknown>(method: string, params?: unknown, timeoutMs?: number, transfer?: Transferable[]): Promise<T>;
|
|
47
|
+
notify(method: string, params?: unknown): void;
|
|
48
|
+
/** Fails every request still waiting and stops listening. */
|
|
49
|
+
close(reason?: string): void;
|
|
50
|
+
private receive;
|
|
51
|
+
private answer;
|
|
52
|
+
}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `ctx.document` inside an extension's worker: `@kition/script`'s document API (`run`, `context`,
|
|
3
|
+
* proxies, `sync()`, `commands`, `changed`) over the host, which runs each batch on the document
|
|
4
|
+
* and checks it against the extension's permissions.
|
|
5
|
+
*/
|
|
6
|
+
import type { BatchRequest, BatchResult, Schema } from '@kition/kdm';
|
|
7
|
+
import { RequestContext, type CommandMap, type ModelObject } from '@kition/script/proxy';
|
|
8
|
+
import type { KitCommandInfo } from '@kition/script';
|
|
9
|
+
import type { DocumentInfo } from '../protocol.js';
|
|
10
|
+
import type { RpcPeer } from '../rpc.js';
|
|
11
|
+
export type DocumentChangedEvent = {
|
|
12
|
+
origin: 'local' | 'kit';
|
|
13
|
+
};
|
|
14
|
+
export declare class ExtensionDocument<Root extends ModelObject = ModelObject, C extends CommandMap = CommandMap> {
|
|
15
|
+
private readonly peer;
|
|
16
|
+
private listeners;
|
|
17
|
+
readonly id: string;
|
|
18
|
+
readonly kitId: string;
|
|
19
|
+
/** The document's file name, when the host gives it. */
|
|
20
|
+
readonly name: string | undefined;
|
|
21
|
+
/** Whether writes are refused (a read-only document, or no `model.write` permission). */
|
|
22
|
+
readonly readOnly: boolean;
|
|
23
|
+
readonly schema: Schema;
|
|
24
|
+
constructor(info: DocumentInfo, peer: RpcPeer);
|
|
25
|
+
/** Runs `script` with a new request context; what it queued and did not `sync()` is sent when it returns. */
|
|
26
|
+
run<T>(script: (context: RequestContext<Root, C>) => Promise<T> | T): Promise<T>;
|
|
27
|
+
context(): RequestContext<Root, C>;
|
|
28
|
+
/** One `model/batch` in its wire form (the host sets its origin). */
|
|
29
|
+
batch(request: BatchRequest): Promise<BatchResult>;
|
|
30
|
+
describe(): Promise<Record<string, unknown>>;
|
|
31
|
+
readonly commands: {
|
|
32
|
+
list: () => Promise<KitCommandInfo[]>;
|
|
33
|
+
enabled: (id: string) => Promise<boolean>;
|
|
34
|
+
run: <K extends keyof C & string>(id: K, params?: C[K]) => Promise<unknown>;
|
|
35
|
+
};
|
|
36
|
+
on(event: 'changed', listener: (event: DocumentChangedEvent) => void): () => void;
|
|
37
|
+
/** The host's `document/changed`. */
|
|
38
|
+
emit(event: DocumentChangedEvent): void;
|
|
39
|
+
close(): void;
|
|
40
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@kition/extensions/runtime`: the extension's side. `startRuntime` serves the host on a port
|
|
3
|
+
* (the sandbox worker runs it); `ExtensionContext` is what an extension's `activate(ctx)` gets.
|
|
4
|
+
* `WORKER_RUNTIME`, `SANDBOX_HTML`, and `PANEL_HTML` are the built worker, sandbox page, and panel
|
|
5
|
+
* page; `KitionPanel` is what a panel's scripts get as `window.kitionPanel`.
|
|
6
|
+
*/
|
|
7
|
+
export { PANEL_HTML, RUNTIME_INPUTS_SHA256, SANDBOX_HTML, WORKER_RUNTIME } from '../generated/runtime.js';
|
|
8
|
+
export { ExtensionDocument, type DocumentChangedEvent } from './document.js';
|
|
9
|
+
export type { KitionPanel } from './panel.js';
|
|
10
|
+
export { startRuntime, type CommandHandler, type ExtensionContext, type ExtensionModule, type ModuleLoader, type PanelConnection, type PanelHandler } from './runtime.js';
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The panel page's only script (bundled into `sandbox/panel.html` by scripts/build-runtime.mjs and
|
|
3
|
+
* allowed by its hash). The host posts it the panel's HTML, the extension's `connect-src`, the
|
|
4
|
+
* host's theme, and the panel's end of a channel to the extension's worker. It adds the
|
|
5
|
+
* `connect-src` policy, gives the panel `kitionPanel` (`request`, `onMessage`, `info`), and then
|
|
6
|
+
* shows the panel's HTML, running its inline scripts in order as blob scripts (the page's CSP
|
|
7
|
+
* allows nothing else).
|
|
8
|
+
*/
|
|
9
|
+
import { type PanelInfo } from '../protocol.js';
|
|
10
|
+
type Listener = (message: unknown) => void;
|
|
11
|
+
/** What the panel's scripts get as `window.kitionPanel`. */
|
|
12
|
+
export type KitionPanel = {
|
|
13
|
+
readonly info: PanelInfo;
|
|
14
|
+
/** Asks the extension's worker (its `panel.onRequest` handler); answers what it answers. */
|
|
15
|
+
request(message: unknown): Promise<unknown>;
|
|
16
|
+
/** Hears what the worker sends (`panel.post(message)`); answers an unsubscribe. */
|
|
17
|
+
onMessage(listener: Listener): () => void;
|
|
18
|
+
};
|
|
19
|
+
export {};
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import type { Notice } from '../protocol.js';
|
|
2
|
+
import { RpcPeer, type PortLike } from '../rpc.js';
|
|
3
|
+
import { ExtensionDocument } from './document.js';
|
|
4
|
+
/** A command handler; what it answers goes back to the host. */
|
|
5
|
+
export type CommandHandler = () => unknown | Promise<unknown>;
|
|
6
|
+
/** One open panel, as the extension's worker sees it: messages to it, and its requests. */
|
|
7
|
+
export type PanelConnection = {
|
|
8
|
+
/** The panel's id (`contributes.panels[].id`). */
|
|
9
|
+
readonly id: string;
|
|
10
|
+
/** This panel's session: a panel shown twice has two. */
|
|
11
|
+
readonly session: string;
|
|
12
|
+
/** Sends `message` to the panel (`kitionPanel.onMessage` there). */
|
|
13
|
+
post(message: unknown): void;
|
|
14
|
+
/** Answers the panel's `kitionPanel.request(message)`; what `handler` answers goes back. */
|
|
15
|
+
onRequest(handler: (message: unknown) => unknown): void;
|
|
16
|
+
/** Runs `listener` when the panel closes; answers a disposer. */
|
|
17
|
+
onClose(listener: () => void): () => void;
|
|
18
|
+
};
|
|
19
|
+
/** Called when a panel of this extension opens on the document; may answer a disposer. */
|
|
20
|
+
export type PanelHandler = (panel: PanelConnection) => unknown;
|
|
21
|
+
/** What `activate(ctx)` (and a script's default export) gets. */
|
|
22
|
+
export type ExtensionContext = {
|
|
23
|
+
extension: {
|
|
24
|
+
id: string;
|
|
25
|
+
name: string;
|
|
26
|
+
version: string;
|
|
27
|
+
permissions: string[];
|
|
28
|
+
};
|
|
29
|
+
/** The document this activation is for. */
|
|
30
|
+
document: ExtensionDocument;
|
|
31
|
+
commands: {
|
|
32
|
+
/** Handles a command the manifest contributes; answers a disposer. */
|
|
33
|
+
register(id: string, handler: CommandHandler): () => void;
|
|
34
|
+
};
|
|
35
|
+
panels: {
|
|
36
|
+
/** Serves a panel the manifest contributes each time it opens on this document; answers a disposer. */
|
|
37
|
+
register(id: string, handler: PanelHandler): () => void;
|
|
38
|
+
};
|
|
39
|
+
/** Shows a message to the person. */
|
|
40
|
+
notify(notice: Notice | string, options?: Omit<Notice, 'title'>): void;
|
|
41
|
+
/** Disposers run when the extension is deactivated on this document. */
|
|
42
|
+
subscriptions: Array<() => void>;
|
|
43
|
+
};
|
|
44
|
+
/** The module an extension's entry is. */
|
|
45
|
+
export type ExtensionModule = {
|
|
46
|
+
activate?: (ctx: ExtensionContext) => unknown;
|
|
47
|
+
deactivate?: (ctx: ExtensionContext) => unknown;
|
|
48
|
+
default?: unknown;
|
|
49
|
+
run?: unknown;
|
|
50
|
+
};
|
|
51
|
+
/** Loads an extension's module from its source. The worker imports a blob URL of it. */
|
|
52
|
+
export type ModuleLoader = (source: string) => Promise<ExtensionModule>;
|
|
53
|
+
/** Serves the host on `port` until it closes; answers the channel. */
|
|
54
|
+
export declare function startRuntime(port: PortLike, load: ModuleLoader): RpcPeer;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import type { ExtensionHost, SandboxFactory } from './host.js';
|
|
2
|
+
export type IframeSandboxOptions = {
|
|
3
|
+
/** Where the host serves the sandbox page. */
|
|
4
|
+
url: string;
|
|
5
|
+
/** Where the hidden frames go (`document.body` by default). */
|
|
6
|
+
container?: HTMLElement;
|
|
7
|
+
/** How long the page may take to load (ms). */
|
|
8
|
+
loadTimeoutMs?: number;
|
|
9
|
+
};
|
|
10
|
+
export declare function iframeSandbox(options: IframeSandboxOptions): SandboxFactory;
|
|
11
|
+
export type PanelFrameOptions = {
|
|
12
|
+
/** Where the host serves the panel page (`sandbox/panel.html`, `PANEL_HTML`). */
|
|
13
|
+
url: string;
|
|
14
|
+
/** Where the panel's frame goes; it fills it. */
|
|
15
|
+
container: HTMLElement;
|
|
16
|
+
/** CSS custom properties for the panel (the host's theme), as `--name: value`. */
|
|
17
|
+
theme?: Record<string, string>;
|
|
18
|
+
/** The host's language, for the panel's `lang`. */
|
|
19
|
+
locale?: string;
|
|
20
|
+
/** How long the page may take to load (ms). */
|
|
21
|
+
loadTimeoutMs?: number;
|
|
22
|
+
/** The frame loaded another page (the panel navigated): it has been removed. */
|
|
23
|
+
onNavigated?: () => void;
|
|
24
|
+
};
|
|
25
|
+
/** A panel shown in a frame. */
|
|
26
|
+
export type PanelFrame = {
|
|
27
|
+
frame: HTMLIFrameElement;
|
|
28
|
+
dispose: () => void;
|
|
29
|
+
};
|
|
30
|
+
/**
|
|
31
|
+
* Shows a contributed panel of an extension for a document in a visible `sandbox="allow-scripts"`
|
|
32
|
+
* frame (an opaque origin, like the extension's worker) loaded from the host's copy of the panel
|
|
33
|
+
* page, with the extension's own `connect-src`. The panel and the extension's worker talk over a
|
|
34
|
+
* `MessageChannel` of their own. A frame that loads another page is removed: a panel never leaves
|
|
35
|
+
* its page (the host's `frame-src` keeps it from loading another origin's).
|
|
36
|
+
*/
|
|
37
|
+
export declare function openPanelFrame(host: Pick<ExtensionHost, 'panelContent' | 'openPanel'>, target: {
|
|
38
|
+
documentId: string;
|
|
39
|
+
extension: string;
|
|
40
|
+
panel: string;
|
|
41
|
+
}, options: PanelFrameOptions): Promise<PanelFrame>;
|
package/package.json
CHANGED
|
@@ -1,6 +1,40 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kition/extensions",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "The Kition extension host (KitExtensions 1.0): extension.json manifests, a sandboxed worker per extension on an opaque origin with declared permissions, and the object model gated by them.",
|
|
5
|
+
"license": "Apache-2.0",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"exports": {
|
|
8
|
+
".": {
|
|
9
|
+
"types": "./dist/types/src/index.d.ts",
|
|
10
|
+
"import": "./dist/index.js"
|
|
11
|
+
},
|
|
12
|
+
"./runtime": {
|
|
13
|
+
"types": "./dist/types/src/runtime/index.d.ts",
|
|
14
|
+
"import": "./dist/runtime.js"
|
|
15
|
+
},
|
|
16
|
+
"./sandbox.html": "./dist/sandbox.html",
|
|
17
|
+
"./panel.html": "./dist/panel.html"
|
|
18
|
+
},
|
|
19
|
+
"files": [
|
|
20
|
+
"dist"
|
|
21
|
+
],
|
|
22
|
+
"dependencies": {
|
|
23
|
+
"@kition/script": "0.2.0",
|
|
24
|
+
"@kition/kdm": "0.2.0"
|
|
25
|
+
},
|
|
26
|
+
"repository": {
|
|
27
|
+
"type": "git",
|
|
28
|
+
"url": "git+https://github.com/KitionAI/kition-sdk.git",
|
|
29
|
+
"directory": "packages/extensions"
|
|
30
|
+
},
|
|
31
|
+
"types": "./dist/types/src/index.d.ts",
|
|
32
|
+
"publishConfig": {
|
|
33
|
+
"access": "public"
|
|
34
|
+
},
|
|
35
|
+
"main": "./dist/index.js",
|
|
36
|
+
"scripts": {
|
|
37
|
+
"build:runtime": "node scripts/build-runtime.mjs",
|
|
38
|
+
"build": "node ../../tools/build-package.mjs"
|
|
39
|
+
}
|
|
6
40
|
}
|
package/README.md
DELETED