@botiverse/porthole 0.5.0 → 0.6.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.
Files changed (90) hide show
  1. package/README.md +25 -0
  2. package/dist/bridge/bridge.d.ts +12 -4
  3. package/dist/bridge/bridge.js +62 -27
  4. package/dist/bridge/navigation.d.ts +6 -0
  5. package/dist/bridge/navigation.js +41 -0
  6. package/dist/bridge/refusal.d.ts +53 -0
  7. package/dist/bridge/refusal.js +121 -0
  8. package/dist/bridge/types.d.ts +7 -0
  9. package/dist/check/check.d.ts +12 -3
  10. package/dist/check/check.js +54 -8
  11. package/dist/check/files.d.ts +26 -0
  12. package/dist/check/files.js +307 -0
  13. package/dist/check/lint.js +27 -10
  14. package/dist/check/page-source.js +1 -1
  15. package/dist/check/page.js +5 -0
  16. package/dist/check/tools.d.ts +23 -0
  17. package/dist/check/tools.js +25 -0
  18. package/dist/compile/policy.d.ts +15 -0
  19. package/dist/compile/policy.js +32 -0
  20. package/dist/config/capabilities.d.ts +5 -0
  21. package/dist/config/schema.d.ts +8 -0
  22. package/dist/config/validate.js +8 -1
  23. package/dist/conformance/harness-source.js +1 -1
  24. package/dist/files/paths.d.ts +99 -0
  25. package/dist/files/paths.js +263 -0
  26. package/dist/files/types.d.ts +24 -0
  27. package/dist/files/types.js +83 -0
  28. package/dist/guide/guide.js +25 -5
  29. package/dist/host/create-host.js +36 -4
  30. package/dist/host/types.d.ts +15 -2
  31. package/dist/index.d.ts +7 -3
  32. package/dist/index.js +10 -3
  33. package/dist/mcp/adapter.js +22 -7
  34. package/dist/protocol/adapter.d.ts +4 -0
  35. package/dist/protocol/mcp-apps.d.ts +12 -0
  36. package/dist/protocol/mcp-apps.js +12 -0
  37. package/dist/protocol/shell-adapter.js +18 -2
  38. package/dist/react/frame.d.ts +19 -4
  39. package/dist/react/frame.js +37 -9
  40. package/dist/server/files.d.ts +44 -0
  41. package/dist/server/files.js +244 -0
  42. package/dist/server/host.d.ts +38 -1
  43. package/dist/server/host.js +37 -2
  44. package/dist/server/index.d.ts +4 -2
  45. package/dist/server/index.js +4 -1
  46. package/dist/server/keys.d.ts +8 -0
  47. package/dist/server/keys.js +34 -0
  48. package/dist/server/server.js +287 -22
  49. package/dist/server/types.d.ts +49 -5
  50. package/dist/shell/document.d.ts +19 -0
  51. package/dist/shell/document.js +30 -0
  52. package/dist/shell/runtime.d.ts +2 -1
  53. package/dist/shell/runtime.js +117 -10
  54. package/docs/ADOPTING.md +95 -13
  55. package/docs/ARCHITECTURE.md +13 -3
  56. package/docs/DECISIONS.md +396 -4
  57. package/docs/DESIGN.md +43 -10
  58. package/package.json +1 -1
  59. package/src/bridge/bridge.ts +74 -23
  60. package/src/bridge/navigation.ts +46 -0
  61. package/src/bridge/refusal.ts +151 -0
  62. package/src/bridge/types.ts +12 -1
  63. package/src/check/check.ts +92 -14
  64. package/src/check/files.ts +384 -0
  65. package/src/check/lint.ts +29 -10
  66. package/src/check/page.ts +7 -0
  67. package/src/check/tools.ts +50 -0
  68. package/src/compile/policy.ts +38 -0
  69. package/src/config/capabilities.ts +5 -1
  70. package/src/config/schema.ts +8 -0
  71. package/src/config/validate.ts +8 -1
  72. package/src/files/paths.ts +323 -0
  73. package/src/files/types.ts +101 -0
  74. package/src/guide/guide.ts +38 -4
  75. package/src/host/create-host.ts +37 -4
  76. package/src/host/types.ts +13 -2
  77. package/src/index.ts +41 -0
  78. package/src/mcp/adapter.ts +26 -6
  79. package/src/protocol/adapter.ts +3 -1
  80. package/src/protocol/mcp-apps.ts +14 -0
  81. package/src/protocol/shell-adapter.ts +20 -2
  82. package/src/react/frame.tsx +53 -14
  83. package/src/server/files.ts +312 -0
  84. package/src/server/host.ts +72 -3
  85. package/src/server/index.ts +19 -0
  86. package/src/server/keys.ts +53 -0
  87. package/src/server/server.ts +353 -24
  88. package/src/server/types.ts +56 -4
  89. package/src/shell/document.ts +53 -0
  90. package/src/shell/runtime.ts +117 -10
@@ -9,6 +9,15 @@ import type { AnnotationReport } from "../annotate/types.ts";
9
9
  import { parseReport } from "../annotate/validate.ts";
10
10
  import type { PortholeConfig } from "../config/schema.ts";
11
11
  import { effectiveGates } from "../compile/policy.ts";
12
+ import { blockedNavigationMessage, withoutSealedAddresses } from "./navigation.ts";
13
+ import {
14
+ defaultReason,
15
+ isRefused,
16
+ pendingReason,
17
+ reasonOf,
18
+ type Refused,
19
+ type RefusalReason,
20
+ } from "./refusal.ts";
12
21
  import type {
13
22
  CallOptions,
14
23
  CallOutcome,
@@ -34,6 +43,8 @@ import type {
34
43
  export type BridgeEvent =
35
44
  | { readonly type: "resize"; readonly height: number; readonly width?: number }
36
45
  | { readonly type: "error"; readonly message: string }
46
+ /** The shell cancelled a navigation of the frame to `url` (P080): the content's word. */
47
+ | { readonly type: "navigationBlocked"; readonly url: string }
37
48
  | { readonly type: "annotation"; readonly report: AnnotationReport }
38
49
  | { readonly type: "refused"; readonly capability: CapabilityName; readonly refusal: Refusal }
39
50
  | { readonly type: "muted" };
@@ -45,9 +56,10 @@ export interface BridgeOptions {
45
56
  readonly confirm?: Confirm;
46
57
  /**
47
58
  * Asked before a `consent`-gated call (P079). The host's, made to ask once per display by the
48
- * caller (`createHost` keeps the answer across the display's frames).
59
+ * caller (`createHost` keeps the answer across the display's frames). A `Refused` refuses every
60
+ * such call with it, asking nothing (P080).
49
61
  */
50
- readonly consent?: Consent;
62
+ readonly consent?: Consent | Refused;
51
63
  /** The host's cache, for reads that may be answered stale (`CallOptions.stale`, P079). */
52
64
  readonly cached?: DataCache;
53
65
  /** Whether the embedding page has user activation now; undefined where it can't tell. */
@@ -143,10 +155,21 @@ const VALIDATORS: { readonly [N in CapabilityName]: Validator<N> } = {
143
155
  ...(structuredContent === undefined ? {} : { structuredContent }),
144
156
  };
145
157
  },
146
- reportError: (args) => {
158
+ reportError: (args, config) => {
159
+ // A navigation the shell cancelled (P080): Porthole words it, naming the address without its
160
+ // query; the address itself goes to the host whole.
161
+ // A frame's sealed files' address never reaches the host from here (P083): `./` instead.
162
+ const blocked = isRecord(args) ? args.navigationBlocked : undefined;
163
+ if (blocked !== undefined) {
164
+ if (typeof blocked !== "string" || blocked === "" || blocked.length > MAX_URL) {
165
+ return null;
166
+ }
167
+ const url = withoutSealedAddresses(blocked);
168
+ return { message: blockedNavigationMessage(url, config), navigationBlocked: url };
169
+ }
147
170
  const message = isRecord(args) ? args.message : undefined;
148
171
  return typeof message === "string" && message !== ""
149
- ? { message: message.slice(0, 2_000) }
172
+ ? { message: withoutSealedAddresses(message).slice(0, 2_000) }
150
173
  : null;
151
174
  },
152
175
  copyText: (args) => {
@@ -174,22 +197,32 @@ const VALIDATORS: { readonly [N in CapabilityName]: Validator<N> } = {
174
197
 
175
198
  /**
176
199
  * The host's `consent`, asked once (P079): the first call asks, every later one gets that answer,
177
- * for as long as the returned function is kept (`createHost` keeps one per display). A consent
178
- * function that fails is a no for that call, and is asked again at the next.
200
+ * for as long as the returned function is kept (`createHost` keeps one per display). A `Refused`
201
+ * it throws is an answer, kept and thrown again at every call (P080); anything else it throws is
202
+ * no answer: thrown for that call, and the next asks again.
179
203
  */
180
204
  export function onceConsent(consent: Consent): Consent {
181
- let answer: Promise<boolean> | null = null;
182
- return (request) =>
183
- (answer ??= Promise.resolve()
205
+ let answer: Promise<boolean | Refused> | null = null;
206
+ return async (request) => {
207
+ const asked = (answer ??= Promise.resolve()
184
208
  .then(() => consent(request))
185
209
  .then(
186
210
  // Only a real yes: anything else a host's function gives is a no (fail closed).
187
211
  (allowed: unknown) => allowed === true,
188
- () => {
212
+ (error: unknown) => {
213
+ if (isRefused(error)) {
214
+ return error;
215
+ }
189
216
  answer = null;
190
- return false;
217
+ throw error;
191
218
  },
192
219
  ));
220
+ const given = await asked;
221
+ if (typeof given !== "boolean") {
222
+ throw given;
223
+ }
224
+ return given;
225
+ };
193
226
  }
194
227
 
195
228
  export function createBridge(options: BridgeOptions): HostFunctionBridge {
@@ -203,9 +236,15 @@ export function createBridge(options: BridgeOptions): HostFunctionBridge {
203
236
  capability: CapabilityName,
204
237
  refusal: Refusal,
205
238
  message?: string,
239
+ reason?: RefusalReason,
206
240
  ): CallOutcome<T> => {
207
241
  onEvent({ type: "refused", capability, refusal });
208
- return { ok: false, refusal, ...(message === undefined ? {} : { message }) };
242
+ return {
243
+ ok: false,
244
+ refusal,
245
+ ...(message === undefined ? {} : { message }),
246
+ reason: reason ?? defaultReason(capability, refusal),
247
+ };
209
248
  };
210
249
 
211
250
  const withinRate = (capability: CapabilityName, perMinute: number): boolean => {
@@ -253,21 +292,27 @@ export function createBridge(options: BridgeOptions): HostFunctionBridge {
253
292
  }
254
293
  }
255
294
  if (gates.includes("consent")) {
256
- if (options.consent === undefined) {
295
+ const consent = options.consent;
296
+ if (consent === undefined) {
257
297
  return refuse<Result>(capability, "no-consent");
258
298
  }
259
- let allowed = false;
299
+ // The host's policy, known before any call: every one refused with its reason (P080).
300
+ if (isRefused(consent)) {
301
+ return refuse<Result>(capability, "denied", undefined, reasonOf(consent));
302
+ }
303
+ let answer: unknown = false;
260
304
  try {
261
- const answer: unknown = await options.consent({
305
+ answer = await consent({ capability, args, display } as ConfirmRequest);
306
+ } catch (error) {
307
+ // A Refused is the host's no, with its reason; any other failure is no answer yet.
308
+ return refuse<Result>(
262
309
  capability,
263
- args,
264
- display,
265
- } as ConfirmRequest);
266
- allowed = answer === true;
267
- } catch {
268
- allowed = false;
310
+ "denied",
311
+ undefined,
312
+ isRefused(error) ? reasonOf(error) : pendingReason(capability),
313
+ );
269
314
  }
270
- if (!allowed) {
315
+ if (answer !== true) {
271
316
  return refuse<Result>(capability, "denied");
272
317
  }
273
318
  }
@@ -321,7 +366,11 @@ export function createBridge(options: BridgeOptions): HostFunctionBridge {
321
366
  } else if (capability === "annotate") {
322
367
  onEvent({ type: "annotation", report: args as CapabilityArgs["annotate"] });
323
368
  } else {
324
- onEvent({ type: "error", message: (args as CapabilityArgs["reportError"]).message });
369
+ const report = args as CapabilityArgs["reportError"];
370
+ if (report.navigationBlocked !== undefined) {
371
+ onEvent({ type: "navigationBlocked", url: report.navigationBlocked });
372
+ }
373
+ onEvent({ type: "error", message: report.message });
325
374
  }
326
375
  return { ok: true, value: undefined as Result };
327
376
  }
@@ -353,10 +402,12 @@ export function createBridge(options: BridgeOptions): HostFunctionBridge {
353
402
  );
354
403
  return { ok: true, value: value as Result };
355
404
  } catch (error) {
405
+ // A host's Refused tells content its reason (P080); any other error stays the host's.
356
406
  return refuse<Result>(
357
407
  capability,
358
408
  "failed",
359
409
  error instanceof Error ? error.message : String(error),
410
+ isRefused(error) ? reasonOf(error) : undefined,
360
411
  );
361
412
  }
362
413
  }
@@ -0,0 +1,46 @@
1
+ import type { PortholeConfig } from "../config/schema.ts";
2
+
3
+ /**
4
+ * A navigation the shell cancelled (P079), as the host is told it (P080): the address, whole, on
5
+ * the `navigationBlocked` event (the host's to keep), and a sentence for the content's errors
6
+ * (`contentError`, which a host may give the agent that wrote it) that names the address without
7
+ * its query or fragment, where a viewer's data would be.
8
+ */
9
+
10
+ /**
11
+ * A frame's sealed files' address (P083) is its access: whatever content says, the host is told
12
+ * it as `./`, the page's own files (the shell says it so already; content may not).
13
+ */
14
+ const SEALED = /(?:https?:\/\/[^\s"'<>/]+)?\/__porthole\/f\/[A-Za-z0-9_-]{20,}\//gu;
15
+ export const withoutSealedAddresses = (text: string): string => text.replace(SEALED, "./");
16
+
17
+ /** An address without what could carry data: an http(s) one's origin and path, else its scheme. */
18
+ export function addressWithoutQuery(url: string): string {
19
+ // A page's own file (P084), as the shell names it: its path, without query or fragment.
20
+ if (url.startsWith("./")) {
21
+ const path = url.split(/[?#]/u)[0] ?? "./";
22
+ return path === url ? path : `${path}?…`;
23
+ }
24
+ let parsed: URL;
25
+ try {
26
+ parsed = new URL(url);
27
+ } catch {
28
+ return "another address";
29
+ }
30
+ if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
31
+ return `a ${parsed.protocol} address`;
32
+ }
33
+ const rest = parsed.search !== "" || parsed.hash !== "" ? "?…" : "";
34
+ return `${parsed.origin}${parsed.pathname}${rest}`;
35
+ }
36
+
37
+ /** What the content's errors say about a navigation the shell cancelled. */
38
+ export function blockedNavigationMessage(url: string, config: PortholeConfig): string {
39
+ const links =
40
+ config.capabilities.openLink === undefined
41
+ ? ""
42
+ : config.mode === "mcp-app"
43
+ ? " Open links with ui/open-link (a new tab)."
44
+ : " Open links with openLink(url) or an <a href> (a new tab).";
45
+ return `It tried to navigate its frame to ${addressWithoutQuery(url)}, and was stopped: content never leaves its page.${links}`;
46
+ }
@@ -0,0 +1,151 @@
1
+ import type { CapabilityName } from "../config/capabilities.ts";
2
+ import type { Refusal } from "./types.ts";
3
+
4
+ /**
5
+ * Why a call was refused, as content is told (P080): a code it can branch on and a sentence it can
6
+ * show the person viewing it. Carried in a refused request's JSON-RPC error, as its `data`; the
7
+ * shell's globals reject with an error that has both (`error.code`, `error.message`).
8
+ *
9
+ * - `consent_required`: the viewer hasn't allowed it yet (their answer is still to come).
10
+ * - `denied`: the viewer (or the person asked to confirm) said no.
11
+ * - `rate_limited`: too many calls this minute.
12
+ * - `not_allowed`: the host doesn't let this content have it, here or at all (a URI it doesn't
13
+ * serve, a page where data never runs).
14
+ * - `failed`: the host tried and couldn't.
15
+ */
16
+ export const REFUSAL_CODES = [
17
+ "consent_required",
18
+ "denied",
19
+ "rate_limited",
20
+ "not_allowed",
21
+ "failed",
22
+ ] as const;
23
+
24
+ export type RefusalCode = (typeof REFUSAL_CODES)[number];
25
+
26
+ /** What content is told about a refusal: the JSON-RPC error's `data`. */
27
+ export interface RefusalReason {
28
+ readonly code: RefusalCode;
29
+ /** A sentence for the person viewing the content: the host's, else Porthole's. */
30
+ readonly message: string;
31
+ }
32
+
33
+ /** The most a refusal's message carries to content. */
34
+ const MAX_MESSAGE = 500;
35
+
36
+ export function isRefusalCode(value: unknown): value is RefusalCode {
37
+ return typeof value === "string" && (REFUSAL_CODES as readonly string[]).includes(value);
38
+ }
39
+
40
+ /**
41
+ * A refusal the host gives, with the reason content is told (P080). Throw it from a handler (this
42
+ * URI isn't one you serve: `not_allowed`; the viewer didn't allow this kind of data: `denied`), or
43
+ * from a `consent` function (kept as the display's answer, as `false` is). Or pass one as
44
+ * `HostOptions.consent` itself: every `consent`-gated call is refused with it, and those
45
+ * capabilities need no handler (a page where data never runs).
46
+ *
47
+ * Any other error a handler throws is `failed` with Porthole's words: its message stays the host's.
48
+ */
49
+ export class Refused extends Error {
50
+ readonly code: RefusalCode;
51
+
52
+ /** `message`: a sentence for the viewer; absent, Porthole's for the code. */
53
+ constructor(code: RefusalCode, message?: string) {
54
+ if (!isRefusalCode(code)) {
55
+ throw new TypeError(`Refused: code must be one of ${REFUSAL_CODES.join(", ")}`);
56
+ }
57
+ super(message === undefined || message.trim() === "" ? DEFAULT_MESSAGES[code] : message);
58
+ this.name = "Refused";
59
+ this.code = code;
60
+ }
61
+ }
62
+
63
+ /**
64
+ * Whether `value` is a `Refused`: by class, or by shape where two copies of Porthole meet (a
65
+ * host's bundle and a library's).
66
+ */
67
+ export function isRefused(value: unknown): value is Refused {
68
+ return (
69
+ value instanceof Refused ||
70
+ (value instanceof Error &&
71
+ value.name === "Refused" &&
72
+ isRefusalCode((value as { code?: unknown }).code))
73
+ );
74
+ }
75
+
76
+ /** The reason a host's `Refused` gives content. */
77
+ export function reasonOf(refused: Refused): RefusalReason {
78
+ const message = refused.message.trim();
79
+ return {
80
+ code: refused.code,
81
+ message: (message === "" ? DEFAULT_MESSAGES[refused.code] : message).slice(0, MAX_MESSAGE),
82
+ };
83
+ }
84
+
85
+ /** Porthole's sentence for each code, where the host gave none. */
86
+ const DEFAULT_MESSAGES: { readonly [Code in RefusalCode]: string } = {
87
+ consent_required: "This needs your permission first.",
88
+ denied: "You didn't allow this.",
89
+ rate_limited: "Too many requests: try again in a minute.",
90
+ not_allowed: "This isn't available here.",
91
+ failed: "The app couldn't do this.",
92
+ };
93
+
94
+ /** Where a data capability's words differ: they name the data. */
95
+ const DATA_MESSAGES: { readonly [Code in RefusalCode]: string } = {
96
+ consent_required: "Reading this data needs your permission first.",
97
+ denied: "You didn't allow this to read your data.",
98
+ rate_limited: "Too many data requests: try again in a minute.",
99
+ not_allowed: "This data isn't available here.",
100
+ failed: "The app couldn't get this data.",
101
+ };
102
+
103
+ /** Each refusal's code, as content is told it. */
104
+ const CODES: { readonly [R in Refusal]: RefusalCode } = {
105
+ "not-declared": "not_allowed",
106
+ invalid: "not_allowed",
107
+ "no-user-activation": "not_allowed",
108
+ "no-confirm": "not_allowed",
109
+ declined: "denied",
110
+ redirected: "denied",
111
+ muted: "denied",
112
+ "no-consent": "not_allowed",
113
+ denied: "denied",
114
+ "rate-limited": "rate_limited",
115
+ failed: "failed",
116
+ };
117
+
118
+ /** Refusals whose own words say more than their code's. */
119
+ const OWN_MESSAGES: { readonly [R in Refusal]?: string } = {
120
+ "no-user-activation": "This needs a click.",
121
+ invalid: "The app can't take this request.",
122
+ muted: "You declined this too often: it isn't asked again until it runs again.",
123
+ };
124
+
125
+ /** What content is told about a refusal Porthole made (the host gave no `Refused`). */
126
+ export function defaultReason(capability: CapabilityName, refusal: Refusal): RefusalReason {
127
+ const code = CODES[refusal];
128
+ const data = capability === "readData" || capability === "subscribeData";
129
+ return {
130
+ code,
131
+ message: OWN_MESSAGES[refusal] ?? (data ? DATA_MESSAGES : DEFAULT_MESSAGES)[code],
132
+ };
133
+ }
134
+
135
+ /** What content is told about a refused call: the bridge's reason, else Porthole's for it. */
136
+ export function reasonFor(
137
+ capability: CapabilityName,
138
+ outcome: { readonly refusal: Refusal; readonly reason?: RefusalReason },
139
+ ): RefusalReason {
140
+ const reason = outcome.reason ?? defaultReason(capability, outcome.refusal);
141
+ return { code: reason.code, message: reason.message };
142
+ }
143
+
144
+ /** A consent function that failed (threw, rejected): not an answer, so asked again at the next. */
145
+ export function pendingReason(capability: CapabilityName): RefusalReason {
146
+ const data = capability === "readData" || capability === "subscribeData";
147
+ return {
148
+ code: "consent_required",
149
+ message: (data ? DATA_MESSAGES : DEFAULT_MESSAGES).consent_required,
150
+ };
151
+ }
@@ -5,6 +5,7 @@ import type {
5
5
  HandledCapability,
6
6
  } from "../config/capabilities.ts";
7
7
  import type { InstanceRef } from "../isolation/types.ts";
8
+ import type { RefusalReason } from "./refusal.ts";
8
9
 
9
10
  /**
10
11
  * The host-function bridge (ARCHITECTURE § Framework layer): carries a capability call from the
@@ -48,6 +49,9 @@ export type CapabilityHandlers = { readonly [N in HandledCapability]?: Capabilit
48
49
  * Asked once per display before its first call of a `consent`-gated capability (P079): may this
49
50
  * content have them (read the viewer's data)? The request is that first call. A host remembers
50
51
  * the answer where it likes (per viewer, per widget); Porthole keeps it for the display's life.
52
+ * `false` is a no (content is told `denied`); a thrown `Refused` is a no with its reason, kept
53
+ * the same way (P080); anything else it throws is no answer yet (`consent_required`), and the next
54
+ * call asks again.
51
55
  */
52
56
  export type Consent = (request: ConfirmRequest) => boolean | Promise<boolean>;
53
57
 
@@ -126,7 +130,14 @@ export type Refusal =
126
130
  export type CallOutcome<T> =
127
131
  /** `stale`: a `readData` answered from the host's cache (`DataCache`). */
128
132
  | { readonly ok: true; readonly value: T; readonly stale?: true }
129
- | { readonly ok: false; readonly refusal: Refusal; readonly message?: string };
133
+ | {
134
+ readonly ok: false;
135
+ readonly refusal: Refusal;
136
+ /** What the host's handler threw: the host's own words, never sent to content. */
137
+ readonly message?: string;
138
+ /** What content is told (P080): the host's `Refused`, else Porthole's for the refusal. */
139
+ readonly reason?: RefusalReason;
140
+ };
130
141
 
131
142
  /** What an adapter adds to a call, beyond what the content sent. */
132
143
  export interface CallOptions {
@@ -3,7 +3,11 @@ import type { InstanceRef } from "../isolation/types.ts";
3
3
  import { presets } from "../presets/presets.ts";
4
4
  import { createServer } from "../server/server.ts";
5
5
  import { CHECK_CONTENT_DOMAIN, CHECK_ORIGIN } from "./drivers.ts";
6
- import { lintContent, type Finding } from "./lint.ts";
6
+ import { lintContent } from "./lint.ts";
7
+ import { lintFiles, whereOf, type FileContents, type FileFinding } from "./files.ts";
8
+ import { DEFAULT_ENTRY, servesFiles } from "../files/paths.ts";
9
+ import { sha256 } from "../server/crypto.ts";
10
+ import type { StoredFiles } from "../server/types.ts";
7
11
  // The check page's script, imported as a module so a bundler takes it in (P075): no file is
8
12
  // looked up beside this one at run time.
9
13
  import PAGE_SCRIPT from "./page-source.ts";
@@ -55,7 +59,15 @@ export interface CheckDriver {
55
59
  export interface CheckOptions {
56
60
  readonly config: PortholeConfig;
57
61
  /** The content as the agent would send it: a fragment, or a whole document. */
58
- readonly content: string;
62
+ readonly content?: string;
63
+ /**
64
+ * A page that comes with files (P081), in place of `content`: every file by its path. The whole
65
+ * set is served, as people's browsers get it, and its entry is run and measured. Needs a served
66
+ * artifact config and a driver that serves (`playwrightDriver`).
67
+ */
68
+ readonly files?: FileContents;
69
+ /** The page a set opens at (default `index.html`). */
70
+ readonly entry?: string;
59
71
  readonly driver: CheckDriver;
60
72
  /** Widths, px. Default: the manual's phone and desktop widths (`config.layout`). */
61
73
  readonly widths?: readonly number[];
@@ -106,7 +118,8 @@ export interface CheckReport {
106
118
  * refuses, overflow or cut, no lint error.
107
119
  */
108
120
  readonly ok: boolean;
109
- readonly lint: readonly Finding[];
121
+ /** What the lint found (for a page with files, each finding names its file, `path`). */
122
+ readonly lint: readonly FileFinding[];
110
123
  readonly runs: readonly CheckRun[];
111
124
  /** One short summary for the agent: each problem once, with where it happened. */
112
125
  readonly text: string;
@@ -130,9 +143,53 @@ function checkedAs(config: PortholeConfig): PortholeConfig {
130
143
 
131
144
  const escapeScript = (code: string) => code.replace(/<\/script/giu, "<\\/script");
132
145
 
146
+ /** A set's own files named by their path, as the agent wrote them, not the frame's address. */
147
+ const ownPaths = (text: string): string =>
148
+ text.replace(/https:\/\/[a-z0-9.-]+\/__porthole\/f\/[\w-]+\//gu, "");
149
+
150
+ const hex = (bytes: Uint8Array): string =>
151
+ Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
152
+
153
+ /** A set's files as the check's server stores them, its entry instrumented (P081). */
154
+ function checkedFiles(files: FileContents, entry: string, page: string): StoredFiles {
155
+ const bytes = (body: string | Uint8Array): Uint8Array =>
156
+ typeof body === "string" ? new TextEncoder().encode(body) : body;
157
+ const served = new Map<string, Uint8Array>(
158
+ Object.entries(files).map(([path, body]) => [path, path === entry ? bytes(page) : bytes(body)]),
159
+ );
160
+ return {
161
+ files: Object.fromEntries(
162
+ [...served].map(([path, body]) => [
163
+ path,
164
+ { size: body.byteLength, sha256: hex(sha256(body)) },
165
+ ]),
166
+ ),
167
+ entry,
168
+ read: (path) => Promise.resolve(served.get(path) ?? null),
169
+ };
170
+ }
171
+
133
172
  export async function checkPage(options: CheckOptions): Promise<CheckReport> {
134
173
  const { config } = options;
135
- const lint = lintContent(config, options.content);
174
+ const entry = options.entry ?? DEFAULT_ENTRY;
175
+ const files = options.files;
176
+ if ((files === undefined) === (options.content === undefined)) {
177
+ throw new TypeError("checkPage takes content, or files: one of them");
178
+ }
179
+ if (files !== undefined && !servesFiles(config)) {
180
+ throw new TypeError("A page with files is checked under a served artifact config");
181
+ }
182
+ const entryText = (): string => {
183
+ const body = files?.[entry];
184
+ return body === undefined
185
+ ? ""
186
+ : typeof body === "string"
187
+ ? body
188
+ : new TextDecoder().decode(body);
189
+ };
190
+ const written = files === undefined ? (options.content ?? "") : entryText();
191
+ const lint: FileFinding[] =
192
+ files === undefined ? lintContent(config, written) : lintFiles(config, files, { entry });
136
193
  if (config.mode === "url") {
137
194
  return {
138
195
  ok: true,
@@ -149,9 +206,13 @@ export async function checkPage(options: CheckOptions): Promise<CheckReport> {
149
206
  const script = options.page ?? PAGE_SCRIPT;
150
207
  const html = `<!doctype html><html><head><meta charset="utf-8"><title>Porthole check</title><style>body{margin:0;padding:8px}section{margin-bottom:16px}</style></head><body><script>${escapeScript(script)}</script></body></html>`;
151
208
  // Its inline scripts named, so an error says the line in the content as written (P074).
152
- const { content, scriptLines } = namedScripts(options.content);
209
+ const { content, scriptLines } = namedScripts(written);
153
210
 
154
211
  const session = await options.driver.open();
212
+ if (files !== undefined && session.serve === undefined) {
213
+ await session.close();
214
+ throw new TypeError("A page with files is checked served: this driver can't serve (no serve)");
215
+ }
155
216
  // A served config runs served, on a content origin the driver answers, under Porthole's own
156
217
  // server: its CSP in headers, its shell, its storage and cookies (P074). Else opaque.
157
218
  const servedHere =
@@ -163,7 +224,14 @@ export async function checkPage(options: CheckOptions): Promise<CheckReport> {
163
224
  secret: crypto.getRandomValues(new Uint8Array(32)),
164
225
  hostOrigins: [CHECK_ORIGIN],
165
226
  configs: { check: servedConfig },
166
- artifacts: { get: () => Promise.resolve({ html: instrumented(content) }) },
227
+ artifacts: {
228
+ get: () =>
229
+ Promise.resolve(
230
+ files === undefined
231
+ ? { html: instrumented(content) }
232
+ : checkedFiles(files, entry, instrumented(content)),
233
+ ),
234
+ },
167
235
  })
168
236
  : null;
169
237
  const handler = async (request: Request): Promise<Response> => {
@@ -240,10 +308,19 @@ export async function checkPage(options: CheckOptions): Promise<CheckReport> {
240
308
  data?.scrollWidth !== undefined &&
241
309
  data.clientWidth !== null &&
242
310
  data.scrollWidth > data.clientWidth + 1,
243
- errors: unique(data?.errors ?? []),
244
- blocked: uniqueBy(data?.blocked ?? [], (each) => `${each.url} ${each.directive}`),
245
- failedLoads: uniqueBy(data?.failedLoads ?? [], (each) => each.url),
246
- console: uniqueBy(data?.console ?? [], (each) => `${each.level} ${each.text}`),
311
+ errors: unique((data?.errors ?? []).map(ownPaths)),
312
+ blocked: uniqueBy(
313
+ (data?.blocked ?? []).map((each) => ({ ...each, url: ownPaths(each.url) })),
314
+ (each) => `${each.url} ${each.directive}`,
315
+ ),
316
+ failedLoads: uniqueBy(
317
+ (data?.failedLoads ?? []).map((each) => ({ ...each, url: ownPaths(each.url) })),
318
+ (each) => each.url,
319
+ ),
320
+ console: uniqueBy(
321
+ (data?.console ?? []).map((each) => ({ ...each, text: ownPaths(each.text) })),
322
+ (each) => `${each.level} ${each.text}`,
323
+ ),
247
324
  calls: uniqueBy(data?.calls ?? [], (each) => `${each.capability} ${each.outcome}`),
248
325
  ...(screenshot === undefined ? {} : { screenshot }),
249
326
  });
@@ -297,7 +374,7 @@ const clip = (text: string, most = 200) =>
297
374
  */
298
375
  function summary(
299
376
  config: PortholeConfig,
300
- lint: readonly Finding[],
377
+ lint: readonly FileFinding[],
301
378
  runs: readonly CheckRun[],
302
379
  most: number,
303
380
  ): string {
@@ -348,9 +425,10 @@ function summary(
348
425
  }
349
426
  }
350
427
  const lines = [
351
- ...lint.map(
352
- (each) =>
353
- `${each.severity === "error" ? "Error" : "Warning"}${each.line === undefined ? "" : ` (line ${each.line})`}: ${each.message}`,
428
+ ...lint.map((each) =>
429
+ each.path === undefined
430
+ ? `${each.severity === "error" ? "Error" : "Warning"}${each.line === undefined ? "" : ` (line ${each.line})`}: ${each.message}`
431
+ : `${each.severity === "error" ? "Error" : "Warning"} (${whereOf(each).replace(/: $/u, "")}): ${each.message}`,
354
432
  ),
355
433
  ...[...where].map(
356
434
  ([problem, at]) =>