@kition/extensions 0.0.0-stage → 0.1.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
package/dist/runtime.js
ADDED
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
import { R as M, E as d } from "./chunks/runtime-BVJHE1Pg.js";
|
|
2
|
+
import { P as N, a as O, S as _, W as H } from "./chunks/runtime-BVJHE1Pg.js";
|
|
3
|
+
import { RequestContext as $ } from "@kition/script/proxy";
|
|
4
|
+
class R {
|
|
5
|
+
constructor(s, o) {
|
|
6
|
+
this.peer = o, this.id = s.documentId, this.kitId = s.kitId, this.name = s.name, this.readOnly = s.readOnly, this.schema = s.schema;
|
|
7
|
+
}
|
|
8
|
+
listeners = /* @__PURE__ */ new Set();
|
|
9
|
+
id;
|
|
10
|
+
kitId;
|
|
11
|
+
/** The document's file name, when the host gives it. */
|
|
12
|
+
name;
|
|
13
|
+
/** Whether writes are refused (a read-only document, or no `model.write` permission). */
|
|
14
|
+
readOnly;
|
|
15
|
+
schema;
|
|
16
|
+
/** Runs `script` with a new request context; what it queued and did not `sync()` is sent when it returns. */
|
|
17
|
+
async run(s) {
|
|
18
|
+
const o = this.context(), l = await s(o);
|
|
19
|
+
return o.queued && await o.sync(), l;
|
|
20
|
+
}
|
|
21
|
+
context() {
|
|
22
|
+
return new $(this.schema, (s) => this.batch(s));
|
|
23
|
+
}
|
|
24
|
+
/** One `model/batch` in its wire form (the host sets its origin). */
|
|
25
|
+
batch(s) {
|
|
26
|
+
return this.peer.request("model/batch", { documentId: this.id, request: s });
|
|
27
|
+
}
|
|
28
|
+
describe() {
|
|
29
|
+
return this.peer.request("model/describe", { documentId: this.id });
|
|
30
|
+
}
|
|
31
|
+
commands = {
|
|
32
|
+
list: () => this.peer.request("model/commands", { documentId: this.id }),
|
|
33
|
+
enabled: async (s) => (await this.commands.list()).some((o) => o.id === s && o.enabled !== !1),
|
|
34
|
+
run: async (s, o) => (await this.batch({ ops: [{ op: "command", id: s, ...o === void 0 ? {} : { params: o } }] })).results[0]
|
|
35
|
+
};
|
|
36
|
+
on(s, o) {
|
|
37
|
+
if (s !== "changed") throw new Error(`unknown event \`${s}\``);
|
|
38
|
+
return this.listeners.add(o), () => {
|
|
39
|
+
this.listeners.delete(o);
|
|
40
|
+
};
|
|
41
|
+
}
|
|
42
|
+
/** The host's `document/changed`. */
|
|
43
|
+
emit(s) {
|
|
44
|
+
for (const o of [...this.listeners])
|
|
45
|
+
try {
|
|
46
|
+
o(s);
|
|
47
|
+
} catch (l) {
|
|
48
|
+
console.error("[kition-extension] a changed listener failed", l);
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
close() {
|
|
52
|
+
this.listeners.clear();
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
const f = (b) => typeof b == "function";
|
|
56
|
+
function A(b, s) {
|
|
57
|
+
const o = new M(b);
|
|
58
|
+
let l = null, x = null, v = "extension";
|
|
59
|
+
const h = /* @__PURE__ */ new Map(), g = /* @__PURE__ */ new Map(), k = (e) => {
|
|
60
|
+
const t = g.get(e);
|
|
61
|
+
if (t) {
|
|
62
|
+
g.delete(e), t.peer.close("the panel closed");
|
|
63
|
+
for (const n of [...t.closed, ...t.dispose ? [t.dispose] : []])
|
|
64
|
+
try {
|
|
65
|
+
n();
|
|
66
|
+
} catch (a) {
|
|
67
|
+
console.error("[kition-extension] a panel close listener failed", a);
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
}, I = (e, t, n, a) => {
|
|
71
|
+
const u = new R(e, o), { id: w, name: m, version: p, permissions: y } = l;
|
|
72
|
+
return {
|
|
73
|
+
extension: { id: w, name: m, version: p, permissions: [...y] },
|
|
74
|
+
document: u,
|
|
75
|
+
commands: {
|
|
76
|
+
register: (i, c) => {
|
|
77
|
+
if (typeof i != "string" || !f(c)) throw new TypeError("commands.register takes a command id and a function");
|
|
78
|
+
if (v === "script") throw new d("invalid", "a script cannot register commands");
|
|
79
|
+
if (!l.contributes.commands.some((r) => r.id === i))
|
|
80
|
+
throw new d("invalid", `${w} does not contribute ${i}: declare it in extension.json contributes.commands`);
|
|
81
|
+
return n.set(i, c), t.push(o.request("commands/register", { documentId: e.documentId, command: i })), () => {
|
|
82
|
+
n.get(i) === c && n.delete(i);
|
|
83
|
+
};
|
|
84
|
+
}
|
|
85
|
+
},
|
|
86
|
+
panels: {
|
|
87
|
+
register: (i, c) => {
|
|
88
|
+
if (typeof i != "string" || !f(c)) throw new TypeError("panels.register takes a panel id and a function");
|
|
89
|
+
if (v === "script") throw new d("invalid", "a script cannot serve panels");
|
|
90
|
+
if (!l.contributes.panels?.some((r) => r.id === i))
|
|
91
|
+
throw new d("invalid", `${w} does not contribute the panel ${i}: declare it in extension.json contributes.panels`);
|
|
92
|
+
return a.set(i, c), () => {
|
|
93
|
+
a.get(i) === c && a.delete(i);
|
|
94
|
+
};
|
|
95
|
+
}
|
|
96
|
+
},
|
|
97
|
+
notify: (i, c) => {
|
|
98
|
+
const r = typeof i == "string" ? { level: c?.level ?? "info", title: i, ...c?.description ? { description: c.description } : {} } : i;
|
|
99
|
+
o.notify("host/notify", r);
|
|
100
|
+
},
|
|
101
|
+
subscriptions: []
|
|
102
|
+
};
|
|
103
|
+
}, E = () => {
|
|
104
|
+
if (!l || !x) throw new d("failed", "the extension has not started");
|
|
105
|
+
return { manifest: l, module: x };
|
|
106
|
+
};
|
|
107
|
+
return o.handle("extension/start", async (e) => {
|
|
108
|
+
if (x) throw new d("invalid", "the extension has already started");
|
|
109
|
+
l = e.manifest, v = e.kind ?? "extension";
|
|
110
|
+
const t = await s(e.source);
|
|
111
|
+
if (v === "script" ? !f(t.default) && !f(t.run) : !f(t.activate))
|
|
112
|
+
throw new d("invalid", v === "script" ? "a script exports a default function (or run)" : `${l.entry} exports no activate function`);
|
|
113
|
+
return x = t, null;
|
|
114
|
+
}).handle("extension/activate", async (e) => {
|
|
115
|
+
const { module: t } = E();
|
|
116
|
+
if (h.has(e.documentId)) return { commands: [...h.get(e.documentId).handlers.keys()] };
|
|
117
|
+
const n = [], a = /* @__PURE__ */ new Map(), u = /* @__PURE__ */ new Map(), w = I(e, n, a, u), m = { context: w, handlers: a, panels: u, disposeActivate: null };
|
|
118
|
+
h.set(e.documentId, m);
|
|
119
|
+
try {
|
|
120
|
+
const p = await t.activate(w);
|
|
121
|
+
f(p) && (m.disposeActivate = p), await Promise.all(n);
|
|
122
|
+
} catch (p) {
|
|
123
|
+
h.delete(e.documentId);
|
|
124
|
+
for (const y of n) y.catch(() => {
|
|
125
|
+
});
|
|
126
|
+
throw p;
|
|
127
|
+
}
|
|
128
|
+
return { commands: [...a.keys()] };
|
|
129
|
+
}).handle("extension/command", async ({ documentId: e, command: t }) => {
|
|
130
|
+
const n = h.get(e)?.handlers.get(t);
|
|
131
|
+
if (!n) throw new d("not-found", `${t} is not registered on ${e}`);
|
|
132
|
+
return await n() ?? null;
|
|
133
|
+
}).handle("extension/deactivate", async ({ documentId: e }) => {
|
|
134
|
+
const t = h.get(e);
|
|
135
|
+
if (!t) return null;
|
|
136
|
+
h.delete(e);
|
|
137
|
+
for (const [a, u] of [...g]) u.documentId === e && k(a);
|
|
138
|
+
const { context: n } = t;
|
|
139
|
+
try {
|
|
140
|
+
await x?.deactivate?.(n), await t.disposeActivate?.();
|
|
141
|
+
} finally {
|
|
142
|
+
for (const a of n.subscriptions.splice(0))
|
|
143
|
+
try {
|
|
144
|
+
a();
|
|
145
|
+
} catch (u) {
|
|
146
|
+
console.error("[kition-extension] a subscription failed to dispose", u);
|
|
147
|
+
}
|
|
148
|
+
n.document.close();
|
|
149
|
+
}
|
|
150
|
+
return null;
|
|
151
|
+
}).handle("script/run", async (e) => {
|
|
152
|
+
const { module: t } = E(), n = f(t.default) ? t.default : t.run, a = I(e, [], /* @__PURE__ */ new Map(), /* @__PURE__ */ new Map());
|
|
153
|
+
return h.set(e.documentId, { context: a, handlers: /* @__PURE__ */ new Map(), panels: /* @__PURE__ */ new Map(), disposeActivate: null }), await n(a) ?? null;
|
|
154
|
+
}).handle("document/changed", ({ documentId: e, origin: t }) => {
|
|
155
|
+
h.get(e)?.context.document.emit({ origin: t });
|
|
156
|
+
}).handle("panel/open", async ({ documentId: e, panel: t, session: n }, a) => {
|
|
157
|
+
const u = h.get(e);
|
|
158
|
+
if (!u) throw new d("not-found", `the extension is not active on ${e}`);
|
|
159
|
+
const w = a[0];
|
|
160
|
+
if (!w) throw new d("invalid", "a panel opens with its port");
|
|
161
|
+
if (g.has(n)) throw new d("invalid", `the panel session ${n} is open already`);
|
|
162
|
+
const m = new M(w);
|
|
163
|
+
let p = null;
|
|
164
|
+
m.handle("panel/request", async (r) => {
|
|
165
|
+
if (!p) throw new d("not-found", `the extension does not answer the panel ${t}`);
|
|
166
|
+
return await p(r) ?? null;
|
|
167
|
+
});
|
|
168
|
+
const y = { documentId: e, peer: m, closed: /* @__PURE__ */ new Set(), dispose: null };
|
|
169
|
+
g.set(n, y);
|
|
170
|
+
const i = {
|
|
171
|
+
id: t,
|
|
172
|
+
session: n,
|
|
173
|
+
post: (r) => m.notify("panel/message", r),
|
|
174
|
+
onRequest: (r) => {
|
|
175
|
+
if (!f(r)) throw new TypeError("onRequest takes a function");
|
|
176
|
+
p = r;
|
|
177
|
+
},
|
|
178
|
+
onClose: (r) => (y.closed.add(r), () => {
|
|
179
|
+
y.closed.delete(r);
|
|
180
|
+
})
|
|
181
|
+
}, c = u.panels.get(t);
|
|
182
|
+
try {
|
|
183
|
+
const r = c ? await c(i) : null;
|
|
184
|
+
f(r) && (y.dispose = r);
|
|
185
|
+
} catch (r) {
|
|
186
|
+
throw k(n), r;
|
|
187
|
+
}
|
|
188
|
+
return null;
|
|
189
|
+
}).handle("panel/close", ({ session: e }) => (k(e), null)), o;
|
|
190
|
+
}
|
|
191
|
+
export {
|
|
192
|
+
R as ExtensionDocument,
|
|
193
|
+
N as PANEL_HTML,
|
|
194
|
+
O as RUNTIME_INPUTS_SHA256,
|
|
195
|
+
_ as SANDBOX_HTML,
|
|
196
|
+
H as WORKER_RUNTIME,
|
|
197
|
+
A as startRuntime
|
|
198
|
+
};
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<!-- Generated by packages/extensions/scripts/build-runtime.mjs from sandbox/bootstrap.js. Do not edit; rebuild it. -->
|
|
3
|
+
<html lang="en">
|
|
4
|
+
<head>
|
|
5
|
+
<meta charset="utf-8">
|
|
6
|
+
<meta http-equiv="Content-Security-Policy" content="script-src 'sha256-w5PK36FENsjJixOfZqEByZ2fjQ+2p/KZc2ZsgQ9e4rs=' blob:; worker-src blob:; object-src 'none'; base-uri 'none'; form-action 'none'; frame-src 'none'; img-src 'none'; media-src 'none'; font-src 'none'; style-src 'none'; manifest-src 'none'">
|
|
7
|
+
<meta name="referrer" content="no-referrer">
|
|
8
|
+
<title>Kition extension sandbox</title>
|
|
9
|
+
<script>// The extension sandbox page's only script (its CSP allows it by hash). The host posts it the
|
|
10
|
+
// worker runtime, the extension's allowed connect-src, and the channel's port; it adds the
|
|
11
|
+
// connect-src policy, starts the worker from a blob, and hands the worker the port.
|
|
12
|
+
;(() => {
|
|
13
|
+
'use strict'
|
|
14
|
+
const TAG = 'kition-ext-sandbox/1'
|
|
15
|
+
const SOURCE = /^(?:'none'|(?:(?:https|wss|http|ws):\/\/(?:\*\.)?[a-z0-9.-]+(?::\d{1,5})?)(?: (?:https|wss|http|ws):\/\/(?:\*\.)?[a-z0-9.-]+(?::\d{1,5})?)*)$/
|
|
16
|
+
let started = false
|
|
17
|
+
addEventListener('message', (event) => {
|
|
18
|
+
const data = event.data
|
|
19
|
+
if (started || event.source !== parent || !data || data.tag !== TAG || data.type !== 'start') return
|
|
20
|
+
const port = event.ports[0]
|
|
21
|
+
if (!port || typeof data.runtime !== 'string' || typeof data.connect !== 'string' || !SOURCE.test(data.connect)) return
|
|
22
|
+
started = true
|
|
23
|
+
const policy = document.createElement('meta')
|
|
24
|
+
policy.httpEquiv = 'Content-Security-Policy'
|
|
25
|
+
policy.content = `connect-src ${data.connect}`
|
|
26
|
+
document.head.appendChild(policy)
|
|
27
|
+
const url = URL.createObjectURL(new Blob([data.runtime], { type: 'text/javascript' }))
|
|
28
|
+
const worker = new Worker(url, { name: 'kition-extension' })
|
|
29
|
+
worker.postMessage({ tag: TAG, type: 'port' }, [port])
|
|
30
|
+
})
|
|
31
|
+
})()
|
|
32
|
+
</script>
|
|
33
|
+
</head>
|
|
34
|
+
<body></body>
|
|
35
|
+
</html>
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What each object-model call needs (`KitExtensions 1.0` permissions). The host checks every
|
|
3
|
+
* call from an extension's worker here before it reaches the document.
|
|
4
|
+
*/
|
|
5
|
+
import type { BatchRequest } from '@kition/kdm';
|
|
6
|
+
import type { KitCommandInfo } from '@kition/script';
|
|
7
|
+
import { type Permission } from './manifest.js';
|
|
8
|
+
import { ExtensionError } from './rpc.js';
|
|
9
|
+
export declare function permissionDenied(extension: string, permission: Permission, what: string): ExtensionError;
|
|
10
|
+
export declare function requirePermission(extension: string, permissions: readonly string[], permission: Permission, what: string): void;
|
|
11
|
+
/**
|
|
12
|
+
* Checks a `model/batch` against `permissions`. Loads need `model.read`; every operation but a
|
|
13
|
+
* command needs `model.write`; a command needs `commands.run`, and `model.write` too unless the
|
|
14
|
+
* kit's catalogue says it does not mutate (`catalogue` answers it; only asked for when the batch
|
|
15
|
+
* has commands).
|
|
16
|
+
*/
|
|
17
|
+
export declare function checkBatch(extension: string, permissions: readonly string[], request: BatchRequest, catalogue: () => Promise<KitCommandInfo[]>): Promise<void>;
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/** A hash of the sources this module was built from (scripts/runtime-inputs.mjs). */
|
|
2
|
+
export declare const RUNTIME_INPUTS_SHA256 = "3071d6975d6f0993907c0a6ea5c8bc97769cd3b4bba46377ebfd63b1404baf6c";
|
|
3
|
+
/** The sandbox worker: one classic script (src/runtime/worker.ts and what it imports). */
|
|
4
|
+
export declare const WORKER_RUNTIME: string;
|
|
5
|
+
/** The sandbox page (sandbox/sandbox.html), for hosts that serve it from memory. */
|
|
6
|
+
export declare const SANDBOX_HTML: string;
|
|
7
|
+
/** The panel page (sandbox/panel.html), for hosts that serve it from memory. */
|
|
8
|
+
export declare const PANEL_HTML: string;
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
import { type ModelPort } from '@kition/script';
|
|
2
|
+
import '@kition/script/kits';
|
|
3
|
+
import { type ExtensionCommand, type ExtensionManifest, type ExtensionPanel, type Permission } from './manifest.js';
|
|
4
|
+
import type { Notice } from './protocol.js';
|
|
5
|
+
import { type PortLike } from './rpc.js';
|
|
6
|
+
/**
|
|
7
|
+
* An installed extension: its manifest, its entry module's source, and its other files as text
|
|
8
|
+
* by package path (each panel's HTML entry).
|
|
9
|
+
*/
|
|
10
|
+
export type ExtensionPackage = {
|
|
11
|
+
manifest: ExtensionManifest | unknown;
|
|
12
|
+
source: string;
|
|
13
|
+
files?: Record<string, string>;
|
|
14
|
+
};
|
|
15
|
+
/** A started sandbox: the channel to its worker, and how to tear it down. */
|
|
16
|
+
export type SandboxConnection = {
|
|
17
|
+
port: PortLike;
|
|
18
|
+
dispose: () => void;
|
|
19
|
+
};
|
|
20
|
+
/**
|
|
21
|
+
* Starts a sandbox for one extension: a worker on an opaque origin that runs `runtime` and may
|
|
22
|
+
* reach only `connect` (a CSP `connect-src` value). `iframeSandbox` is the one for pages.
|
|
23
|
+
*/
|
|
24
|
+
export type SandboxFactory = (options: {
|
|
25
|
+
id: string;
|
|
26
|
+
connect: string;
|
|
27
|
+
}) => Promise<SandboxConnection>;
|
|
28
|
+
/** A document open in the host that extensions may work on. */
|
|
29
|
+
export type HostDocument = {
|
|
30
|
+
/** The host's id for it (Kition: its workspace path). */
|
|
31
|
+
id: string;
|
|
32
|
+
kitId: string;
|
|
33
|
+
/** Its path or file name; `activation.formats` match its extension. */
|
|
34
|
+
path?: string;
|
|
35
|
+
/** The document's object model port (`portFromConnection`, `portFromEngine`, …). */
|
|
36
|
+
port: ModelPort;
|
|
37
|
+
/** The kit's schema when the kit is not registered with `@kition/script` (`registerKit`). */
|
|
38
|
+
schema?: object;
|
|
39
|
+
};
|
|
40
|
+
export type ExtensionNotice = Notice & {
|
|
41
|
+
extension: string;
|
|
42
|
+
};
|
|
43
|
+
export type ExtensionHostOptions = {
|
|
44
|
+
sandbox: SandboxFactory;
|
|
45
|
+
/** The kit's schema for documents that bring none; `@kition/script`'s registered kits otherwise. */
|
|
46
|
+
schema?: (kitId: string) => object | undefined;
|
|
47
|
+
/** `ctx.notify` of extensions, and the host's reports of their failures. */
|
|
48
|
+
notify?: (notice: ExtensionNotice) => void;
|
|
49
|
+
/** How long a sandbox may take to start an extension (ms). */
|
|
50
|
+
startTimeoutMs?: number;
|
|
51
|
+
};
|
|
52
|
+
/** A contributed command as a host lists it (palette, menus). */
|
|
53
|
+
export type ContributedCommand = ExtensionCommand & {
|
|
54
|
+
extension: string;
|
|
55
|
+
extensionName: string;
|
|
56
|
+
};
|
|
57
|
+
/** A contributed panel as a host lists it. */
|
|
58
|
+
export type ContributedPanel = ExtensionPanel & {
|
|
59
|
+
extension: string;
|
|
60
|
+
extensionName: string;
|
|
61
|
+
};
|
|
62
|
+
/** What a host needs to show a panel: its HTML and its `connect-src` (the extension's). */
|
|
63
|
+
export type PanelContent = {
|
|
64
|
+
html: string;
|
|
65
|
+
connect: string;
|
|
66
|
+
title: string;
|
|
67
|
+
};
|
|
68
|
+
/** A panel open on a document; `close` ends it in the extension's worker. */
|
|
69
|
+
export type PanelSession = {
|
|
70
|
+
session: string;
|
|
71
|
+
close: () => void;
|
|
72
|
+
};
|
|
73
|
+
/** The permissions of a script run with `runScript`. */
|
|
74
|
+
export declare const SCRIPT_PERMISSIONS: Permission[];
|
|
75
|
+
type Activation = {
|
|
76
|
+
commands: Set<string>;
|
|
77
|
+
unsubscribe: () => void;
|
|
78
|
+
};
|
|
79
|
+
export declare class ExtensionHost {
|
|
80
|
+
private readonly options;
|
|
81
|
+
private loaded;
|
|
82
|
+
private documents;
|
|
83
|
+
private scripts;
|
|
84
|
+
private panelSessions;
|
|
85
|
+
constructor(options: ExtensionHostOptions);
|
|
86
|
+
/** Checks and loads an extension (its code runs when it is first activated); replaces one with its id. */
|
|
87
|
+
load(pkg: ExtensionPackage): ExtensionManifest;
|
|
88
|
+
/** Deactivates an extension everywhere and stops its sandbox. */
|
|
89
|
+
unload(id: string): void;
|
|
90
|
+
extensions(): ExtensionManifest[];
|
|
91
|
+
/** Offers a document to extensions; those that activate on open do. Answers `closeDocument`. */
|
|
92
|
+
openDocument(document: HostDocument): () => void;
|
|
93
|
+
/** Deactivates every extension on the document. */
|
|
94
|
+
closeDocument(id: string): void;
|
|
95
|
+
/** The commands loaded extensions contribute to a document, in load order. */
|
|
96
|
+
commandsFor(documentId: string): ContributedCommand[];
|
|
97
|
+
/** The panels loaded extensions contribute to a document, in load order. */
|
|
98
|
+
panelsFor(documentId: string): ContributedPanel[];
|
|
99
|
+
/** A contributed panel's HTML and the network origins its frame may reach (the extension's). */
|
|
100
|
+
panelContent(extensionId: string, panelId: string): PanelContent;
|
|
101
|
+
/**
|
|
102
|
+
* Opens a contributed panel on a document: activates the extension there first when needed, then
|
|
103
|
+
* hands its worker `port`, the worker's end of the panel's channel (the panel's frame gets the
|
|
104
|
+
* other end). Answers the session; closing the document or the extension closes it too.
|
|
105
|
+
*/
|
|
106
|
+
openPanel(documentId: string, extensionId: string, panelId: string, port: MessagePort): Promise<PanelSession>;
|
|
107
|
+
/** Runs a contributed command on a document, activating its extension first when needed. */
|
|
108
|
+
runCommand(documentId: string, extensionId: string, commandId: string): Promise<unknown>;
|
|
109
|
+
/** Activates an extension on a document (once); answers when its `activate` has returned. */
|
|
110
|
+
activate(extensionId: string, documentId: string): Promise<Activation>;
|
|
111
|
+
/**
|
|
112
|
+
* Runs a script (an ES module whose default export, or `run`, takes the same `ctx` as
|
|
113
|
+
* `activate`) once against a document, in a sandbox of its own with `permissions`. Answers what
|
|
114
|
+
* it answers.
|
|
115
|
+
*/
|
|
116
|
+
runScript(script: {
|
|
117
|
+
source: string;
|
|
118
|
+
name?: string;
|
|
119
|
+
}, documentId: string, permissions?: Permission[]): Promise<unknown>;
|
|
120
|
+
/** Stops every sandbox and forgets every document. */
|
|
121
|
+
dispose(): void;
|
|
122
|
+
private require;
|
|
123
|
+
private info;
|
|
124
|
+
private activateReporting;
|
|
125
|
+
private report;
|
|
126
|
+
/** The document's object model, opened once and shared by every extension on it. */
|
|
127
|
+
private model;
|
|
128
|
+
/** The sandbox of an extension, started once. */
|
|
129
|
+
private start;
|
|
130
|
+
private stop;
|
|
131
|
+
private deactivate;
|
|
132
|
+
/** What the extension's worker may ask of the host. */
|
|
133
|
+
private serve;
|
|
134
|
+
}
|
|
135
|
+
export {};
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@kition/extensions`: the extension host (`KitExtensions 1.0`). A host loads extensions
|
|
3
|
+
* (`extension.json` + one ES module), runs each in a sandboxed worker on an opaque origin with only
|
|
4
|
+
* its declared network origins, and serves it the object model (`@kition/script`) of the documents it
|
|
5
|
+
* is active on, checked against its permissions. Extension authors: see `@kition/extensions/runtime`
|
|
6
|
+
* for `activate(ctx)`'s types.
|
|
7
|
+
*/
|
|
8
|
+
export { checkBatch, permissionDenied, requirePermission } from './gate.js';
|
|
9
|
+
export { ExtensionHost, SCRIPT_PERMISSIONS, type ContributedCommand, type ContributedPanel, type PanelContent, type PanelSession, type ExtensionHostOptions, type ExtensionNotice, type ExtensionPackage, type HostDocument, type SandboxConnection, type SandboxFactory } from './host.js';
|
|
10
|
+
export { appliesTo, connectSources, hasPermission, KIT_EXTENSIONS_CAPABILITY, MANIFEST_VERSION, ManifestError, networkSources, panelAppliesTo, parseManifest, type ExtensionActivation, type ExtensionCommand, type ExtensionManifest, type ExtensionPanel, type Permission, } from './manifest.js';
|
|
11
|
+
export { PANEL_TAG, SANDBOX_TAG, type DocumentInfo, type HostToWorker, type Notice, type PanelChannel, type PanelInfo, type PanelStart, type SandboxStart, type WorkerToHost } from './protocol.js';
|
|
12
|
+
export { CHANNEL_TAG, ExtensionError, RpcPeer, type PortLike } from './rpc.js';
|
|
13
|
+
export { iframeSandbox, openPanelFrame, type IframeSandboxOptions, type PanelFrame, type PanelFrameOptions } from './sandbox.js';
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `extension.json` (`KitExtensions 1.0`): what an extension is, which documents it applies to,
|
|
3
|
+
* what it adds, and what it may do. Everything here is checked before any of its code runs.
|
|
4
|
+
*/
|
|
5
|
+
export declare const KIT_EXTENSIONS_CAPABILITY = "KitExtensions 1.0";
|
|
6
|
+
/** The manifest version this host reads. */
|
|
7
|
+
export declare const MANIFEST_VERSION = "1.0";
|
|
8
|
+
/**
|
|
9
|
+
* - `model.read`: read the document (`load`, `describe`, the command catalogue).
|
|
10
|
+
* - `model.write`: change it (every write operation; a mutating command also needs it).
|
|
11
|
+
* - `commands.run`: run the kit's commands.
|
|
12
|
+
* - `network:<origin>`: reach that origin (`fetch`, WebSocket, …); nothing else is reachable.
|
|
13
|
+
*/
|
|
14
|
+
export type Permission = 'model.read' | 'model.write' | 'commands.run' | `network:${string}`;
|
|
15
|
+
export type ExtensionCommand = {
|
|
16
|
+
id: string;
|
|
17
|
+
title: string;
|
|
18
|
+
description?: string;
|
|
19
|
+
};
|
|
20
|
+
/**
|
|
21
|
+
* A panel the extension draws next to the kit's editor: one self-contained HTML file of the
|
|
22
|
+
* package (`entry`), shown in a sandboxed frame that talks to the extension's worker. `kits`
|
|
23
|
+
* narrows the documents it is offered for to some of `activation.kits`.
|
|
24
|
+
*/
|
|
25
|
+
export type ExtensionPanel = {
|
|
26
|
+
id: string;
|
|
27
|
+
title: string;
|
|
28
|
+
entry: string;
|
|
29
|
+
kits?: string[];
|
|
30
|
+
};
|
|
31
|
+
export type ExtensionActivation = {
|
|
32
|
+
/** The kits the extension applies to (`kit.slide`, …). */
|
|
33
|
+
kits: string[];
|
|
34
|
+
/** File extensions (no dot) that narrow `kits`; every file of those kits when absent. */
|
|
35
|
+
formats?: string[];
|
|
36
|
+
/** `open`: activate when a matching document opens; `command` (default): on its first command. */
|
|
37
|
+
on?: 'open' | 'command';
|
|
38
|
+
};
|
|
39
|
+
export type ExtensionManifest = {
|
|
40
|
+
kitExtensions: typeof MANIFEST_VERSION;
|
|
41
|
+
/** Reverse domain name, lower case: `com.example.title-case`. */
|
|
42
|
+
id: string;
|
|
43
|
+
name: string;
|
|
44
|
+
/** Semantic version. */
|
|
45
|
+
version: string;
|
|
46
|
+
description?: string;
|
|
47
|
+
publisher?: string;
|
|
48
|
+
/** The ES module, relative to the package: one self-contained file (no relative imports). */
|
|
49
|
+
entry: string;
|
|
50
|
+
activation: ExtensionActivation;
|
|
51
|
+
contributes: {
|
|
52
|
+
commands: ExtensionCommand[];
|
|
53
|
+
panels?: ExtensionPanel[];
|
|
54
|
+
};
|
|
55
|
+
permissions: Permission[];
|
|
56
|
+
};
|
|
57
|
+
/** A manifest this host refuses, with every problem found. */
|
|
58
|
+
export declare class ManifestError extends Error {
|
|
59
|
+
readonly problems: string[];
|
|
60
|
+
constructor(problems: string[]);
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* The origins a `network:` permission names, as CSP sources: `network:api.example.com` is
|
|
64
|
+
* `https://api.example.com` and `wss://api.example.com`; a scheme may be given (`https`, `wss`,
|
|
65
|
+
* or `http`/`ws` for loopback only), and a port. Answers `null` when it is not one.
|
|
66
|
+
*/
|
|
67
|
+
export declare function networkSources(permission: string): string[] | null;
|
|
68
|
+
/** The CSP `connect-src` value for `permissions`: their declared origins, or `'none'`. */
|
|
69
|
+
export declare function connectSources(permissions: readonly string[]): string;
|
|
70
|
+
export declare const hasPermission: (permissions: readonly string[], permission: Permission) => boolean;
|
|
71
|
+
/** Reads and checks an `extension.json` (text or parsed); throws `ManifestError` with every problem. */
|
|
72
|
+
export declare function parseManifest(input: unknown): ExtensionManifest;
|
|
73
|
+
/** Whether `manifest` applies to a document of `kitId` at `path`. */
|
|
74
|
+
export declare function appliesTo(manifest: ExtensionManifest, document: {
|
|
75
|
+
kitId: string;
|
|
76
|
+
path?: string;
|
|
77
|
+
}): boolean;
|
|
78
|
+
/** Whether `panel` of `manifest` is offered for a document of `kitId` at `path`. */
|
|
79
|
+
export declare function panelAppliesTo(manifest: ExtensionManifest, panel: ExtensionPanel, document: {
|
|
80
|
+
kitId: string;
|
|
81
|
+
path?: string;
|
|
82
|
+
}): boolean;
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The methods between the host and an extension's worker (`KitExtensions 1.0`). The host starts
|
|
3
|
+
* the extension, activates it per document, and runs its commands; the worker reads and edits the
|
|
4
|
+
* documents it is active on through the host, which checks every call against its permissions.
|
|
5
|
+
*/
|
|
6
|
+
import type { BatchRequest, BatchResult } from '@kition/kdm';
|
|
7
|
+
import type { KitCommandInfo } from '@kition/script';
|
|
8
|
+
import type { ExtensionManifest } from './manifest.js';
|
|
9
|
+
/** The message the host posts to the sandbox page with the channel's port (see `sandbox/`). */
|
|
10
|
+
export declare const SANDBOX_TAG = "kition-ext-sandbox/1";
|
|
11
|
+
export type SandboxStart = {
|
|
12
|
+
tag: typeof SANDBOX_TAG;
|
|
13
|
+
type: 'start';
|
|
14
|
+
runtime: string;
|
|
15
|
+
connect: string;
|
|
16
|
+
};
|
|
17
|
+
/** The message the host posts to a panel page (`sandbox/panel.html`) with the panel's port. */
|
|
18
|
+
export declare const PANEL_TAG = "kition-ext-panel/1";
|
|
19
|
+
export type PanelStart = {
|
|
20
|
+
tag: typeof PANEL_TAG;
|
|
21
|
+
type: 'start';
|
|
22
|
+
/** The panel's HTML (its entry file). */
|
|
23
|
+
html: string;
|
|
24
|
+
/** Its CSP `connect-src`: the extension's `network:` origins, or `'none'`. */
|
|
25
|
+
connect: string;
|
|
26
|
+
/** CSS custom properties for the panel's root (the host's theme), as `--name: value`. */
|
|
27
|
+
theme?: Record<string, string>;
|
|
28
|
+
info: PanelInfo;
|
|
29
|
+
};
|
|
30
|
+
/** What a panel knows of itself (`kitionPanel.info` in the panel). */
|
|
31
|
+
export type PanelInfo = {
|
|
32
|
+
extension: string;
|
|
33
|
+
panel: string;
|
|
34
|
+
documentId: string;
|
|
35
|
+
title: string;
|
|
36
|
+
locale?: string;
|
|
37
|
+
};
|
|
38
|
+
export type DocumentInfo = {
|
|
39
|
+
documentId: string;
|
|
40
|
+
kitId: string;
|
|
41
|
+
/** The document's file name in the host (no folders), when it has one. */
|
|
42
|
+
name?: string;
|
|
43
|
+
/** The kit's KDM schema: the proxies need it. */
|
|
44
|
+
schema: object;
|
|
45
|
+
/** Whether writes are refused: the document is read-only, or the extension may not write. */
|
|
46
|
+
readOnly: boolean;
|
|
47
|
+
};
|
|
48
|
+
/** Host to worker. */
|
|
49
|
+
export type HostToWorker = {
|
|
50
|
+
/** Loads the extension's module (`kind: script` for a script run once). */
|
|
51
|
+
'extension/start': {
|
|
52
|
+
params: {
|
|
53
|
+
manifest: ExtensionManifest;
|
|
54
|
+
source: string;
|
|
55
|
+
kind?: 'extension' | 'script';
|
|
56
|
+
};
|
|
57
|
+
result: null;
|
|
58
|
+
};
|
|
59
|
+
/** Calls `activate(ctx)` for one document; answers the commands it registered. */
|
|
60
|
+
'extension/activate': {
|
|
61
|
+
params: DocumentInfo;
|
|
62
|
+
result: {
|
|
63
|
+
commands: string[];
|
|
64
|
+
};
|
|
65
|
+
};
|
|
66
|
+
'extension/command': {
|
|
67
|
+
params: {
|
|
68
|
+
documentId: string;
|
|
69
|
+
command: string;
|
|
70
|
+
};
|
|
71
|
+
result: unknown;
|
|
72
|
+
};
|
|
73
|
+
'extension/deactivate': {
|
|
74
|
+
params: {
|
|
75
|
+
documentId: string;
|
|
76
|
+
};
|
|
77
|
+
result: null;
|
|
78
|
+
};
|
|
79
|
+
/** A script's default export, run once against the document. */
|
|
80
|
+
'script/run': {
|
|
81
|
+
params: DocumentInfo;
|
|
82
|
+
result: unknown;
|
|
83
|
+
};
|
|
84
|
+
/** Notification: the document changed (`local`: the extension's own batch). */
|
|
85
|
+
'document/changed': {
|
|
86
|
+
params: {
|
|
87
|
+
documentId: string;
|
|
88
|
+
origin: 'local' | 'kit';
|
|
89
|
+
};
|
|
90
|
+
result: never;
|
|
91
|
+
};
|
|
92
|
+
/** A panel opened on a document: its `MessagePort` comes with the request (`session` names it). */
|
|
93
|
+
'panel/open': {
|
|
94
|
+
params: {
|
|
95
|
+
documentId: string;
|
|
96
|
+
panel: string;
|
|
97
|
+
session: string;
|
|
98
|
+
};
|
|
99
|
+
result: null;
|
|
100
|
+
};
|
|
101
|
+
'panel/close': {
|
|
102
|
+
params: {
|
|
103
|
+
session: string;
|
|
104
|
+
};
|
|
105
|
+
result: null;
|
|
106
|
+
};
|
|
107
|
+
};
|
|
108
|
+
/** Between a panel and the extension's worker, over the panel's own channel. */
|
|
109
|
+
export type PanelChannel = {
|
|
110
|
+
/** Panel to worker: what the panel asks; the worker's `onRequest` handler answers. */
|
|
111
|
+
'panel/request': {
|
|
112
|
+
params: unknown;
|
|
113
|
+
result: unknown;
|
|
114
|
+
};
|
|
115
|
+
/** Notification, worker to panel: `panel.post(message)`. */
|
|
116
|
+
'panel/message': {
|
|
117
|
+
params: unknown;
|
|
118
|
+
result: never;
|
|
119
|
+
};
|
|
120
|
+
};
|
|
121
|
+
/** Worker to host. */
|
|
122
|
+
export type WorkerToHost = {
|
|
123
|
+
'model/batch': {
|
|
124
|
+
params: {
|
|
125
|
+
documentId: string;
|
|
126
|
+
request: BatchRequest;
|
|
127
|
+
};
|
|
128
|
+
result: BatchResult;
|
|
129
|
+
};
|
|
130
|
+
'model/describe': {
|
|
131
|
+
params: {
|
|
132
|
+
documentId: string;
|
|
133
|
+
};
|
|
134
|
+
result: Record<string, unknown>;
|
|
135
|
+
};
|
|
136
|
+
'model/commands': {
|
|
137
|
+
params: {
|
|
138
|
+
documentId: string;
|
|
139
|
+
};
|
|
140
|
+
result: KitCommandInfo[];
|
|
141
|
+
};
|
|
142
|
+
'commands/register': {
|
|
143
|
+
params: {
|
|
144
|
+
documentId: string;
|
|
145
|
+
command: string;
|
|
146
|
+
};
|
|
147
|
+
result: null;
|
|
148
|
+
};
|
|
149
|
+
/** Notification: a message for the person. */
|
|
150
|
+
'host/notify': {
|
|
151
|
+
params: Notice;
|
|
152
|
+
result: never;
|
|
153
|
+
};
|
|
154
|
+
};
|
|
155
|
+
export type Notice = {
|
|
156
|
+
level: 'info' | 'success' | 'warning' | 'error';
|
|
157
|
+
title: string;
|
|
158
|
+
description?: string;
|
|
159
|
+
};
|