@botiverse/porthole 0.5.1 → 0.7.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 +41 -0
- package/dist/bridge/bridge.d.ts +13 -0
- package/dist/bridge/bridge.js +208 -13
- package/dist/bridge/navigation.d.ts +1 -6
- package/dist/bridge/navigation.js +11 -0
- package/dist/bridge/refusal.d.ts +5 -1
- package/dist/bridge/refusal.js +16 -0
- package/dist/bridge/types.d.ts +41 -4
- package/dist/check/check.d.ts +19 -3
- package/dist/check/check.js +55 -8
- package/dist/check/files.d.ts +26 -0
- package/dist/check/files.js +307 -0
- package/dist/check/instrument.d.ts +3 -0
- package/dist/check/lint.js +31 -12
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +14 -0
- package/dist/check/tools.d.ts +23 -0
- package/dist/check/tools.js +27 -3
- package/dist/compile/policy.d.ts +34 -0
- package/dist/compile/policy.js +74 -0
- package/dist/config/capabilities.d.ts +62 -3
- package/dist/config/capabilities.js +20 -0
- package/dist/config/schema.d.ts +32 -0
- package/dist/config/validate.d.ts +1 -1
- package/dist/config/validate.js +74 -5
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/index.d.ts +1 -0
- package/dist/conformance/index.js +2 -0
- package/dist/conformance/runtime.d.ts +58 -0
- package/dist/conformance/runtime.js +314 -0
- package/dist/files/paths.d.ts +99 -0
- package/dist/files/paths.js +263 -0
- package/dist/files/types.d.ts +24 -0
- package/dist/files/types.js +83 -0
- package/dist/guide/gates.d.ts +3 -0
- package/dist/guide/gates.js +19 -0
- package/dist/guide/guide.d.ts +2 -0
- package/dist/guide/guide.js +44 -32
- package/dist/guide/limits.js +4 -4
- package/dist/guide/runtime.d.ts +13 -0
- package/dist/guide/runtime.js +202 -0
- package/dist/host/create-host.js +45 -0
- package/dist/host/locate.js +8 -0
- package/dist/host/locator.js +7 -0
- package/dist/host/types.d.ts +18 -0
- package/dist/index.d.ts +13 -4
- package/dist/index.js +16 -3
- package/dist/isolation/types.d.ts +8 -0
- package/dist/presets/presets.d.ts +6 -0
- package/dist/presets/presets.js +1 -0
- package/dist/protocol/adapter.d.ts +4 -0
- package/dist/protocol/mcp-apps.d.ts +6 -0
- package/dist/protocol/mcp-apps.js +6 -0
- package/dist/protocol/runtime-calls.d.ts +28 -0
- package/dist/protocol/runtime-calls.js +113 -0
- package/dist/protocol/shell-adapter.js +52 -3
- package/dist/react/dialog.js +31 -0
- package/dist/react/frame.d.ts +13 -0
- package/dist/react/frame.js +6 -0
- package/dist/runtime/contract.d.ts +193 -0
- package/dist/runtime/contract.js +216 -0
- package/dist/runtime/db.d.ts +153 -0
- package/dist/runtime/db.js +398 -0
- package/dist/runtime/declaration.d.ts +86 -0
- package/dist/runtime/declaration.js +266 -0
- package/dist/runtime/levels.d.ts +33 -0
- package/dist/runtime/levels.js +41 -0
- package/dist/runtime/requests.d.ts +125 -0
- package/dist/runtime/requests.js +199 -0
- package/dist/runtime/segments.d.ts +8 -0
- package/dist/runtime/segments.js +14 -0
- package/dist/runtime/types.generated.d.ts +1 -0
- package/dist/runtime/types.generated.js +19 -0
- package/dist/server/files.d.ts +57 -0
- package/dist/server/files.js +338 -0
- package/dist/server/host.d.ts +44 -2
- package/dist/server/host.js +42 -2
- package/dist/server/index.d.ts +5 -2
- package/dist/server/index.js +5 -1
- package/dist/server/keys.d.ts +8 -0
- package/dist/server/keys.js +34 -0
- package/dist/server/pseudonym.d.ts +9 -0
- package/dist/server/pseudonym.js +20 -0
- package/dist/server/server.d.ts +0 -5
- package/dist/server/server.js +468 -24
- package/dist/server/types.d.ts +118 -5
- package/dist/shell/document.d.ts +27 -0
- package/dist/shell/document.js +46 -2
- package/dist/shell/legacy.d.ts +21 -0
- package/dist/shell/legacy.js +63 -0
- package/dist/shell/plan.d.ts +17 -1
- package/dist/shell/plan.js +13 -2
- package/dist/shell/runtime.d.ts +2 -1
- package/dist/shell/runtime.js +114 -46
- package/dist/shell/use.d.ts +15 -0
- package/dist/shell/use.js +235 -0
- package/docs/ADOPTING.md +142 -5
- package/docs/ARCHITECTURE.md +34 -5
- package/docs/DECISIONS.md +716 -7
- package/docs/DESIGN.md +97 -3
- package/package.json +3 -1
- package/src/bridge/bridge.ts +281 -17
- package/src/bridge/navigation.ts +12 -0
- package/src/bridge/refusal.ts +16 -0
- package/src/bridge/types.ts +46 -4
- package/src/check/check.ts +100 -14
- package/src/check/files.ts +384 -0
- package/src/check/instrument.ts +3 -0
- package/src/check/lint.ts +33 -12
- package/src/check/page.ts +14 -0
- package/src/check/tools.ts +52 -3
- package/src/compile/policy.ts +92 -0
- package/src/config/capabilities.ts +49 -2
- package/src/config/schema.ts +32 -0
- package/src/config/validate.ts +107 -5
- package/src/conformance/index.ts +7 -0
- package/src/conformance/runtime.ts +573 -0
- package/src/files/paths.ts +323 -0
- package/src/files/types.ts +101 -0
- package/src/guide/gates.ts +25 -0
- package/src/guide/guide.ts +78 -52
- package/src/guide/limits.ts +4 -4
- package/src/guide/runtime.ts +244 -0
- package/src/host/create-host.ts +55 -0
- package/src/host/locate.ts +10 -0
- package/src/host/locator.ts +11 -0
- package/src/host/types.ts +18 -0
- package/src/index.ts +121 -0
- package/src/isolation/types.ts +8 -0
- package/src/presets/presets.ts +7 -0
- package/src/protocol/adapter.ts +3 -1
- package/src/protocol/mcp-apps.ts +7 -0
- package/src/protocol/runtime-calls.ts +138 -0
- package/src/protocol/shell-adapter.ts +56 -2
- package/src/react/dialog.tsx +33 -0
- package/src/react/frame.tsx +19 -0
- package/src/runtime/contract.ts +305 -0
- package/src/runtime/db.ts +530 -0
- package/src/runtime/declaration.ts +378 -0
- package/src/runtime/levels.ts +69 -0
- package/src/runtime/requests.ts +339 -0
- package/src/runtime/segments.ts +17 -0
- package/src/runtime/types.generated.ts +19 -0
- package/src/server/files.ts +425 -0
- package/src/server/host.ts +84 -3
- package/src/server/index.ts +22 -0
- package/src/server/keys.ts +53 -0
- package/src/server/pseudonym.ts +21 -0
- package/src/server/server.ts +565 -26
- package/src/server/types.ts +124 -4
- package/src/shell/document.ts +74 -4
- package/src/shell/legacy.ts +64 -0
- package/src/shell/plan.ts +37 -3
- package/src/shell/runtime.ts +114 -46
- package/src/shell/use.ts +235 -0
- package/types/runtime/v1/artifact.d.ts +50 -0
- package/types/runtime/v1/assets.d.ts +43 -0
- package/types/runtime/v1/chat.d.ts +13 -0
- package/types/runtime/v1/clipboard.d.ts +14 -0
- package/types/runtime/v1/comments.d.ts +24 -0
- package/types/runtime/v1/context.d.ts +16 -0
- package/types/runtime/v1/data.d.ts +29 -0
- package/types/runtime/v1/db.d.ts +110 -0
- package/types/runtime/v1/downloads.d.ts +22 -0
- package/types/runtime/v1/links.d.ts +13 -0
- package/types/runtime/v1/porthole.d.ts +44 -0
- package/types/runtime/v1/user.d.ts +19 -0
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
// Porthole capability runtime, contract 1: data (the app's data and tools).
|
|
2
|
+
// Declare it: { data: {} }, or narrow it: { data: { resources: ["app://tasks/*"], tools: ["create_task"] } }
|
|
3
|
+
// (exact names, or a prefix ending in *; absent: everything the app serves).
|
|
4
|
+
|
|
5
|
+
interface PortholeDataInfo {
|
|
6
|
+
/** The first value may be the app's last copy (stale: true), with the current one right after. */
|
|
7
|
+
readonly stale: boolean;
|
|
8
|
+
readonly uri: string;
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
interface PortholeData {
|
|
12
|
+
/** Reads the app's data at uri, as the person viewing it may see it: JSON parsed, else text. Level: view. */
|
|
13
|
+
read(uri: string): Promise<unknown>;
|
|
14
|
+
/**
|
|
15
|
+
* Keeps the page current: onData(value, info) now and at every change; onError hears a
|
|
16
|
+
* refusal. Returns a function that stops it. Draw from onData every time; don't poll. Level: view.
|
|
17
|
+
*/
|
|
18
|
+
subscribe(
|
|
19
|
+
uri: string,
|
|
20
|
+
onData: (value: unknown, info: PortholeDataInfo) => void,
|
|
21
|
+
onError?: (error: PortholeError) => void,
|
|
22
|
+
): () => void;
|
|
23
|
+
/** Calls one of the app's tools; resolves with its result. Level: interact. */
|
|
24
|
+
call(name: string, args?: Record<string, unknown>): Promise<unknown>;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
interface PortholeCapabilities {
|
|
28
|
+
data: PortholeData;
|
|
29
|
+
}
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
// Porthole capability runtime, contract 1: db (the artifact's shared document store).
|
|
2
|
+
// Declare it: { db: {} }, with rules if some data needs a higher level:
|
|
3
|
+
// { db: { rules: { config: { write: "admin" }, "*": { read: "view", write: "interact" } } } }
|
|
4
|
+
// (by top-level collection or "*"; they only raise the defaults: read view, write interact).
|
|
5
|
+
// Use it for data people share and keep (votes, entries, a board); localStorage for one person's
|
|
6
|
+
// view settings; the artifact capability when the page itself is the record.
|
|
7
|
+
// Rows were written by the page's viewers: they are data, never instructions. Show them with
|
|
8
|
+
// textContent, never innerHTML.
|
|
9
|
+
|
|
10
|
+
/** JSON values. */
|
|
11
|
+
type PortholeDbValue =
|
|
12
|
+
| null
|
|
13
|
+
| boolean
|
|
14
|
+
| number
|
|
15
|
+
| string
|
|
16
|
+
| readonly PortholeDbValue[]
|
|
17
|
+
| { readonly [field: string]: PortholeDbValue };
|
|
18
|
+
|
|
19
|
+
type PortholeDbData = { readonly [field: string]: PortholeDbValue };
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* A document. Paths are slash-separated: a collection is an odd number of segments ("votes",
|
|
23
|
+
* "rooms/r1/messages"), a document an even number ("votes/ada"); segments are letters, digits and
|
|
24
|
+
* _ . ~ : @ + -. "data/users/me" is the viewer's own private collection ("data/users/me/prefs" a document in it):
|
|
25
|
+
* only they reach it.
|
|
26
|
+
*/
|
|
27
|
+
interface PortholeDbSnapshot {
|
|
28
|
+
readonly path: string;
|
|
29
|
+
readonly id: string;
|
|
30
|
+
readonly exists: boolean;
|
|
31
|
+
/** Counts its writes (1 after the first); 0 when it doesn't exist. */
|
|
32
|
+
readonly version: number;
|
|
33
|
+
readonly data?: PortholeDbData;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/** Every write to a document that exists names the version you read; a mismatch rejects with conflict. ifVersion 0: it must not exist yet. */
|
|
37
|
+
interface PortholeDbWriteOptions {
|
|
38
|
+
readonly ifVersion?: number;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
type PortholeDbWrite =
|
|
42
|
+
| {
|
|
43
|
+
readonly op: "set";
|
|
44
|
+
readonly path: string;
|
|
45
|
+
readonly data: PortholeDbData;
|
|
46
|
+
readonly ifVersion?: number;
|
|
47
|
+
}
|
|
48
|
+
| {
|
|
49
|
+
readonly op: "update";
|
|
50
|
+
readonly path: string;
|
|
51
|
+
readonly data: PortholeDbData;
|
|
52
|
+
readonly ifVersion?: number;
|
|
53
|
+
}
|
|
54
|
+
| { readonly op: "delete"; readonly path: string; readonly ifVersion?: number };
|
|
55
|
+
|
|
56
|
+
interface PortholeDbQuery {
|
|
57
|
+
/** At most 10: [field, op, value]. */
|
|
58
|
+
readonly where?: readonly (readonly [
|
|
59
|
+
field: string,
|
|
60
|
+
op: "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "array-contains",
|
|
61
|
+
value: PortholeDbValue,
|
|
62
|
+
])[];
|
|
63
|
+
readonly orderBy?: { readonly field: string; readonly direction?: "asc" | "desc" };
|
|
64
|
+
/** 1 to 500. */
|
|
65
|
+
readonly limit?: number;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
interface PortholeDb {
|
|
69
|
+
/** Level: view. */
|
|
70
|
+
get(path: string): Promise<PortholeDbSnapshot>;
|
|
71
|
+
/** A collection's documents. Level: view. */
|
|
72
|
+
query(
|
|
73
|
+
collection: string,
|
|
74
|
+
query?: PortholeDbQuery,
|
|
75
|
+
): Promise<{ readonly docs: readonly PortholeDbSnapshot[] }>;
|
|
76
|
+
/** Writes a whole document (at most 1 MiB of JSON). Level: interact. */
|
|
77
|
+
set(
|
|
78
|
+
path: string,
|
|
79
|
+
data: PortholeDbData,
|
|
80
|
+
options?: PortholeDbWriteOptions,
|
|
81
|
+
): Promise<{ readonly version: number }>;
|
|
82
|
+
/** Merges fields over a document's. Level: interact. */
|
|
83
|
+
update(
|
|
84
|
+
path: string,
|
|
85
|
+
data: PortholeDbData,
|
|
86
|
+
options?: PortholeDbWriteOptions,
|
|
87
|
+
): Promise<{ readonly version: number }>;
|
|
88
|
+
/** Level: interact. */
|
|
89
|
+
delete(path: string, options?: PortholeDbWriteOptions): Promise<null>;
|
|
90
|
+
/**
|
|
91
|
+
* Up to 50 writes to different documents, all or none. Each write's new version (null for a
|
|
92
|
+
* delete). Each write at its own level.
|
|
93
|
+
*/
|
|
94
|
+
batch(
|
|
95
|
+
writes: readonly PortholeDbWrite[],
|
|
96
|
+
): Promise<{ readonly versions: readonly (number | null)[] }>;
|
|
97
|
+
/**
|
|
98
|
+
* Follows a document (a snapshot) or a collection ({ docs }) now and at every change. Returns a
|
|
99
|
+
* function that stops it. Draw from onData; don't poll. Level: view.
|
|
100
|
+
*/
|
|
101
|
+
onSnapshot(
|
|
102
|
+
path: string,
|
|
103
|
+
onData: (state: PortholeDbSnapshot | { readonly docs: readonly PortholeDbSnapshot[] }) => void,
|
|
104
|
+
onError?: (error: PortholeError) => void,
|
|
105
|
+
): () => void;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
interface PortholeCapabilities {
|
|
109
|
+
db: PortholeDb;
|
|
110
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
// Porthole capability runtime, contract 1: downloads. Built in: never declare it.
|
|
2
|
+
|
|
3
|
+
/** A file to hand the person: its name, and its text or bytes. */
|
|
4
|
+
interface PortholeDownload {
|
|
5
|
+
/** A file name, no slashes: "report.csv". Its extension gives its type unless `type` says. */
|
|
6
|
+
readonly name: string;
|
|
7
|
+
readonly type?: string;
|
|
8
|
+
readonly text?: string;
|
|
9
|
+
readonly data?: Blob | ArrayBuffer | ArrayBufferView;
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
interface PortholeDownloads {
|
|
13
|
+
/**
|
|
14
|
+
* Hands the person a file to save (<a download> and script-driven saves don't work here).
|
|
15
|
+
* Call it from a click. Resolves true if the download started. Level: view.
|
|
16
|
+
*/
|
|
17
|
+
save(file: PortholeDownload): Promise<boolean>;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
interface PortholeCapabilities {
|
|
21
|
+
downloads: PortholeDownloads;
|
|
22
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
// Porthole capability runtime, contract 1: links. Built in: never declare it.
|
|
2
|
+
|
|
3
|
+
interface PortholeLinks {
|
|
4
|
+
/**
|
|
5
|
+
* Opens an http(s) link outside the page (a click on an <a href> does the same). Call it from
|
|
6
|
+
* a click. Resolves true if it opened. Level: view.
|
|
7
|
+
*/
|
|
8
|
+
open(url: string): Promise<boolean>;
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
interface PortholeCapabilities {
|
|
12
|
+
links: PortholeLinks;
|
|
13
|
+
}
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
// Porthole capability runtime, contract 1: the call contract (how a page reaches any capability).
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Why a call was refused: branch on it; show `message` (a sentence for the person) where the
|
|
5
|
+
* result would be. Never retry in a loop.
|
|
6
|
+
* - consent_required: the person hasn't allowed it yet.
|
|
7
|
+
* - denied: the person said no.
|
|
8
|
+
* - rate_limited: too many calls this minute.
|
|
9
|
+
* - not_allowed: not available here (some places show the page without it).
|
|
10
|
+
* - failed: the app tried and couldn't.
|
|
11
|
+
* - forbidden: this person may see the page but not do this (their level).
|
|
12
|
+
* - conflict: what you change moved since you read it: read it again, then write.
|
|
13
|
+
* - too_large: past a limit.
|
|
14
|
+
*/
|
|
15
|
+
type PortholeErrorCode =
|
|
16
|
+
| "consent_required"
|
|
17
|
+
| "denied"
|
|
18
|
+
| "rate_limited"
|
|
19
|
+
| "not_allowed"
|
|
20
|
+
| "failed"
|
|
21
|
+
| "forbidden"
|
|
22
|
+
| "conflict"
|
|
23
|
+
| "too_large";
|
|
24
|
+
|
|
25
|
+
/** What every capability method rejects with. */
|
|
26
|
+
interface PortholeError extends Error {
|
|
27
|
+
readonly code: PortholeErrorCode;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** Each capability's namespace, by the name `use` takes (each capability's own file adds its own). */
|
|
31
|
+
interface PortholeCapabilities {}
|
|
32
|
+
|
|
33
|
+
interface PortholeRuntime {
|
|
34
|
+
/**
|
|
35
|
+
* The capability's namespace, frozen; or null when it isn't there for this page: the app
|
|
36
|
+
* doesn't offer it, the page didn't declare it, or no app is showing the page (a tab, a
|
|
37
|
+
* preview). The reasons are indistinguishable: draw the page without it. `use` never rejects;
|
|
38
|
+
* permission problems come when you call a method (a rejected promise, `PortholeError`).
|
|
39
|
+
*/
|
|
40
|
+
use<N extends keyof PortholeCapabilities>(name: N): Promise<PortholeCapabilities[N] | null>;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** The page's one global. Nothing else is added to `window`. */
|
|
44
|
+
declare const porthole: PortholeRuntime;
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
// Porthole capability runtime, contract 1: user. Declare it: { user: {} }.
|
|
2
|
+
|
|
3
|
+
/** Who is viewing, as the app says. */
|
|
4
|
+
interface PortholeUserInfo {
|
|
5
|
+
/** The app's id for this person (whose data "data/users/me" is), or null if it gives none. */
|
|
6
|
+
readonly id: string | null;
|
|
7
|
+
readonly name: string | null;
|
|
8
|
+
/** What they may do here: view < interact < admin < owner. */
|
|
9
|
+
readonly level: "view" | "interact" | "admin" | "owner";
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
interface PortholeUser {
|
|
13
|
+
/** Level: view. */
|
|
14
|
+
get(): Promise<PortholeUserInfo>;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
interface PortholeCapabilities {
|
|
18
|
+
user: PortholeUser;
|
|
19
|
+
}
|