@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.
Files changed (167) hide show
  1. package/README.md +41 -0
  2. package/dist/bridge/bridge.d.ts +13 -0
  3. package/dist/bridge/bridge.js +208 -13
  4. package/dist/bridge/navigation.d.ts +1 -6
  5. package/dist/bridge/navigation.js +11 -0
  6. package/dist/bridge/refusal.d.ts +5 -1
  7. package/dist/bridge/refusal.js +16 -0
  8. package/dist/bridge/types.d.ts +41 -4
  9. package/dist/check/check.d.ts +19 -3
  10. package/dist/check/check.js +55 -8
  11. package/dist/check/files.d.ts +26 -0
  12. package/dist/check/files.js +307 -0
  13. package/dist/check/instrument.d.ts +3 -0
  14. package/dist/check/lint.js +31 -12
  15. package/dist/check/page-source.js +1 -1
  16. package/dist/check/page.js +14 -0
  17. package/dist/check/tools.d.ts +23 -0
  18. package/dist/check/tools.js +27 -3
  19. package/dist/compile/policy.d.ts +34 -0
  20. package/dist/compile/policy.js +74 -0
  21. package/dist/config/capabilities.d.ts +62 -3
  22. package/dist/config/capabilities.js +20 -0
  23. package/dist/config/schema.d.ts +32 -0
  24. package/dist/config/validate.d.ts +1 -1
  25. package/dist/config/validate.js +74 -5
  26. package/dist/conformance/harness-source.js +1 -1
  27. package/dist/conformance/index.d.ts +1 -0
  28. package/dist/conformance/index.js +2 -0
  29. package/dist/conformance/runtime.d.ts +58 -0
  30. package/dist/conformance/runtime.js +314 -0
  31. package/dist/files/paths.d.ts +99 -0
  32. package/dist/files/paths.js +263 -0
  33. package/dist/files/types.d.ts +24 -0
  34. package/dist/files/types.js +83 -0
  35. package/dist/guide/gates.d.ts +3 -0
  36. package/dist/guide/gates.js +19 -0
  37. package/dist/guide/guide.d.ts +2 -0
  38. package/dist/guide/guide.js +44 -32
  39. package/dist/guide/limits.js +4 -4
  40. package/dist/guide/runtime.d.ts +13 -0
  41. package/dist/guide/runtime.js +202 -0
  42. package/dist/host/create-host.js +45 -0
  43. package/dist/host/locate.js +8 -0
  44. package/dist/host/locator.js +7 -0
  45. package/dist/host/types.d.ts +18 -0
  46. package/dist/index.d.ts +13 -4
  47. package/dist/index.js +16 -3
  48. package/dist/isolation/types.d.ts +8 -0
  49. package/dist/presets/presets.d.ts +6 -0
  50. package/dist/presets/presets.js +1 -0
  51. package/dist/protocol/adapter.d.ts +4 -0
  52. package/dist/protocol/mcp-apps.d.ts +6 -0
  53. package/dist/protocol/mcp-apps.js +6 -0
  54. package/dist/protocol/runtime-calls.d.ts +28 -0
  55. package/dist/protocol/runtime-calls.js +113 -0
  56. package/dist/protocol/shell-adapter.js +52 -3
  57. package/dist/react/dialog.js +31 -0
  58. package/dist/react/frame.d.ts +13 -0
  59. package/dist/react/frame.js +6 -0
  60. package/dist/runtime/contract.d.ts +193 -0
  61. package/dist/runtime/contract.js +216 -0
  62. package/dist/runtime/db.d.ts +153 -0
  63. package/dist/runtime/db.js +398 -0
  64. package/dist/runtime/declaration.d.ts +86 -0
  65. package/dist/runtime/declaration.js +266 -0
  66. package/dist/runtime/levels.d.ts +33 -0
  67. package/dist/runtime/levels.js +41 -0
  68. package/dist/runtime/requests.d.ts +125 -0
  69. package/dist/runtime/requests.js +199 -0
  70. package/dist/runtime/segments.d.ts +8 -0
  71. package/dist/runtime/segments.js +14 -0
  72. package/dist/runtime/types.generated.d.ts +1 -0
  73. package/dist/runtime/types.generated.js +19 -0
  74. package/dist/server/files.d.ts +57 -0
  75. package/dist/server/files.js +338 -0
  76. package/dist/server/host.d.ts +44 -2
  77. package/dist/server/host.js +42 -2
  78. package/dist/server/index.d.ts +5 -2
  79. package/dist/server/index.js +5 -1
  80. package/dist/server/keys.d.ts +8 -0
  81. package/dist/server/keys.js +34 -0
  82. package/dist/server/pseudonym.d.ts +9 -0
  83. package/dist/server/pseudonym.js +20 -0
  84. package/dist/server/server.d.ts +0 -5
  85. package/dist/server/server.js +468 -24
  86. package/dist/server/types.d.ts +118 -5
  87. package/dist/shell/document.d.ts +27 -0
  88. package/dist/shell/document.js +46 -2
  89. package/dist/shell/legacy.d.ts +21 -0
  90. package/dist/shell/legacy.js +63 -0
  91. package/dist/shell/plan.d.ts +17 -1
  92. package/dist/shell/plan.js +13 -2
  93. package/dist/shell/runtime.d.ts +2 -1
  94. package/dist/shell/runtime.js +114 -46
  95. package/dist/shell/use.d.ts +15 -0
  96. package/dist/shell/use.js +235 -0
  97. package/docs/ADOPTING.md +142 -5
  98. package/docs/ARCHITECTURE.md +34 -5
  99. package/docs/DECISIONS.md +716 -7
  100. package/docs/DESIGN.md +97 -3
  101. package/package.json +3 -1
  102. package/src/bridge/bridge.ts +281 -17
  103. package/src/bridge/navigation.ts +12 -0
  104. package/src/bridge/refusal.ts +16 -0
  105. package/src/bridge/types.ts +46 -4
  106. package/src/check/check.ts +100 -14
  107. package/src/check/files.ts +384 -0
  108. package/src/check/instrument.ts +3 -0
  109. package/src/check/lint.ts +33 -12
  110. package/src/check/page.ts +14 -0
  111. package/src/check/tools.ts +52 -3
  112. package/src/compile/policy.ts +92 -0
  113. package/src/config/capabilities.ts +49 -2
  114. package/src/config/schema.ts +32 -0
  115. package/src/config/validate.ts +107 -5
  116. package/src/conformance/index.ts +7 -0
  117. package/src/conformance/runtime.ts +573 -0
  118. package/src/files/paths.ts +323 -0
  119. package/src/files/types.ts +101 -0
  120. package/src/guide/gates.ts +25 -0
  121. package/src/guide/guide.ts +78 -52
  122. package/src/guide/limits.ts +4 -4
  123. package/src/guide/runtime.ts +244 -0
  124. package/src/host/create-host.ts +55 -0
  125. package/src/host/locate.ts +10 -0
  126. package/src/host/locator.ts +11 -0
  127. package/src/host/types.ts +18 -0
  128. package/src/index.ts +121 -0
  129. package/src/isolation/types.ts +8 -0
  130. package/src/presets/presets.ts +7 -0
  131. package/src/protocol/adapter.ts +3 -1
  132. package/src/protocol/mcp-apps.ts +7 -0
  133. package/src/protocol/runtime-calls.ts +138 -0
  134. package/src/protocol/shell-adapter.ts +56 -2
  135. package/src/react/dialog.tsx +33 -0
  136. package/src/react/frame.tsx +19 -0
  137. package/src/runtime/contract.ts +305 -0
  138. package/src/runtime/db.ts +530 -0
  139. package/src/runtime/declaration.ts +378 -0
  140. package/src/runtime/levels.ts +69 -0
  141. package/src/runtime/requests.ts +339 -0
  142. package/src/runtime/segments.ts +17 -0
  143. package/src/runtime/types.generated.ts +19 -0
  144. package/src/server/files.ts +425 -0
  145. package/src/server/host.ts +84 -3
  146. package/src/server/index.ts +22 -0
  147. package/src/server/keys.ts +53 -0
  148. package/src/server/pseudonym.ts +21 -0
  149. package/src/server/server.ts +565 -26
  150. package/src/server/types.ts +124 -4
  151. package/src/shell/document.ts +74 -4
  152. package/src/shell/legacy.ts +64 -0
  153. package/src/shell/plan.ts +37 -3
  154. package/src/shell/runtime.ts +114 -46
  155. package/src/shell/use.ts +235 -0
  156. package/types/runtime/v1/artifact.d.ts +50 -0
  157. package/types/runtime/v1/assets.d.ts +43 -0
  158. package/types/runtime/v1/chat.d.ts +13 -0
  159. package/types/runtime/v1/clipboard.d.ts +14 -0
  160. package/types/runtime/v1/comments.d.ts +24 -0
  161. package/types/runtime/v1/context.d.ts +16 -0
  162. package/types/runtime/v1/data.d.ts +29 -0
  163. package/types/runtime/v1/db.d.ts +110 -0
  164. package/types/runtime/v1/downloads.d.ts +22 -0
  165. package/types/runtime/v1/links.d.ts +13 -0
  166. package/types/runtime/v1/porthole.d.ts +44 -0
  167. package/types/runtime/v1/user.d.ts +19 -0
@@ -2,6 +2,9 @@ import { presets } from "../presets/presets.js";
2
2
  import { createServer } from "../server/server.js";
3
3
  import { CHECK_CONTENT_DOMAIN, CHECK_ORIGIN } from "./drivers.js";
4
4
  import { lintContent } from "./lint.js";
5
+ import { lintFiles, whereOf } from "./files.js";
6
+ import { DEFAULT_ENTRY, servesFiles } from "../files/paths.js";
7
+ import { sha256 } from "../server/crypto.js";
5
8
  // The check page's script, imported as a module so a bundler takes it in (P075): no file is
6
9
  // looked up beside this one at run time.
7
10
  import PAGE_SCRIPT from "./page-source.js";
@@ -21,9 +24,42 @@ function checkedAs(config) {
21
24
  : opaque;
22
25
  }
23
26
  const escapeScript = (code) => code.replace(/<\/script/giu, "<\\/script");
27
+ /** A set's own files named by their path, as the agent wrote them, not the frame's address. */
28
+ const ownPaths = (text) => text.replace(/https:\/\/[a-z0-9.-]+\/__porthole\/f\/[\w-]+\//gu, "");
29
+ const hex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
30
+ /** A set's files as the check's server stores them, its entry instrumented (P081). */
31
+ function checkedFiles(files, entry, page) {
32
+ const bytes = (body) => typeof body === "string" ? new TextEncoder().encode(body) : body;
33
+ const served = new Map(Object.entries(files).map(([path, body]) => [path, path === entry ? bytes(page) : bytes(body)]));
34
+ return {
35
+ files: Object.fromEntries([...served].map(([path, body]) => [
36
+ path,
37
+ { size: body.byteLength, sha256: hex(sha256(body)) },
38
+ ])),
39
+ entry,
40
+ read: (path) => Promise.resolve(served.get(path) ?? null),
41
+ };
42
+ }
24
43
  export async function checkPage(options) {
25
44
  const { config } = options;
26
- const lint = lintContent(config, options.content);
45
+ const entry = options.entry ?? DEFAULT_ENTRY;
46
+ const files = options.files;
47
+ if ((files === undefined) === (options.content === undefined)) {
48
+ throw new TypeError("checkPage takes content, or files: one of them");
49
+ }
50
+ if (files !== undefined && !servesFiles(config)) {
51
+ throw new TypeError("A page with files is checked under a served artifact config");
52
+ }
53
+ const entryText = () => {
54
+ const body = files?.[entry];
55
+ return body === undefined
56
+ ? ""
57
+ : typeof body === "string"
58
+ ? body
59
+ : new TextDecoder().decode(body);
60
+ };
61
+ const written = files === undefined ? (options.content ?? "") : entryText();
62
+ const lint = files === undefined ? lintContent(config, written) : lintFiles(config, files, { entry });
27
63
  if (config.mode === "url") {
28
64
  return {
29
65
  ok: true,
@@ -40,8 +76,12 @@ export async function checkPage(options) {
40
76
  const script = options.page ?? PAGE_SCRIPT;
41
77
  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>`;
42
78
  // Its inline scripts named, so an error says the line in the content as written (P074).
43
- const { content, scriptLines } = namedScripts(options.content);
79
+ const { content, scriptLines } = namedScripts(written);
44
80
  const session = await options.driver.open();
81
+ if (files !== undefined && session.serve === undefined) {
82
+ await session.close();
83
+ throw new TypeError("A page with files is checked served: this driver can't serve (no serve)");
84
+ }
45
85
  // A served config runs served, on a content origin the driver answers, under Porthole's own
46
86
  // server: its CSP in headers, its shell, its storage and cookies (P074). Else opaque.
47
87
  const servedHere = config.isolation === "domain" && config.mode !== "mcp-app" && session.serve !== undefined;
@@ -52,7 +92,11 @@ export async function checkPage(options) {
52
92
  secret: crypto.getRandomValues(new Uint8Array(32)),
53
93
  hostOrigins: [CHECK_ORIGIN],
54
94
  configs: { check: servedConfig },
55
- artifacts: { get: () => Promise.resolve({ html: instrumented(content) }) },
95
+ artifacts: {
96
+ get: () => Promise.resolve(files === undefined
97
+ ? { html: instrumented(content) }
98
+ : checkedFiles(files, entry, instrumented(content))),
99
+ },
56
100
  })
57
101
  : null;
58
102
  const handler = async (request) => {
@@ -97,6 +141,7 @@ export async function checkPage(options) {
97
141
  content,
98
142
  scriptLines,
99
143
  ...(instance === undefined ? {} : { instance }),
144
+ ...(options.declaration === undefined ? {} : { declaration: options.declaration }),
100
145
  widthPx: width,
101
146
  ...(fills ? { heightPx: 700 } : {}),
102
147
  scheme,
@@ -122,10 +167,10 @@ export async function checkPage(options) {
122
167
  data?.scrollWidth !== undefined &&
123
168
  data.clientWidth !== null &&
124
169
  data.scrollWidth > data.clientWidth + 1,
125
- errors: unique(data?.errors ?? []),
126
- blocked: uniqueBy(data?.blocked ?? [], (each) => `${each.url} ${each.directive}`),
127
- failedLoads: uniqueBy(data?.failedLoads ?? [], (each) => each.url),
128
- console: uniqueBy(data?.console ?? [], (each) => `${each.level} ${each.text}`),
170
+ errors: unique((data?.errors ?? []).map(ownPaths)),
171
+ blocked: uniqueBy((data?.blocked ?? []).map((each) => ({ ...each, url: ownPaths(each.url) })), (each) => `${each.url} ${each.directive}`),
172
+ failedLoads: uniqueBy((data?.failedLoads ?? []).map((each) => ({ ...each, url: ownPaths(each.url) })), (each) => each.url),
173
+ console: uniqueBy((data?.console ?? []).map((each) => ({ ...each, text: ownPaths(each.text) })), (each) => `${each.level} ${each.text}`),
129
174
  calls: uniqueBy(data?.calls ?? [], (each) => `${each.capability} ${each.outcome}`),
130
175
  ...(screenshot === undefined ? {} : { screenshot }),
131
176
  });
@@ -211,7 +256,9 @@ function summary(config, lint, runs, most) {
211
256
  }
212
257
  }
213
258
  const lines = [
214
- ...lint.map((each) => `${each.severity === "error" ? "Error" : "Warning"}${each.line === undefined ? "" : ` (line ${each.line})`}: ${each.message}`),
259
+ ...lint.map((each) => each.path === undefined
260
+ ? `${each.severity === "error" ? "Error" : "Warning"}${each.line === undefined ? "" : ` (line ${each.line})`}: ${each.message}`
261
+ : `${each.severity === "error" ? "Error" : "Warning"} (${whereOf(each).replace(/: $/u, "")}): ${each.message}`),
215
262
  ...[...where].map(([problem, at]) => `${problem} (at ${at.length === runs.length ? "every width and scheme" : at.join(", ")}).`),
216
263
  ];
217
264
  const ran = `${[...new Set(runs.map((run) => `${run.width} px`))].join(" and ")}, ${[...new Set(runs.map((run) => run.scheme))].join(" and ")}`;
@@ -0,0 +1,26 @@
1
+ import type { PortholeConfig } from "../config/schema.ts";
2
+ import { type Finding } from "./lint.ts";
3
+ /**
4
+ * What can be told about a page that comes with files (P081), without running it: each page
5
+ * linted as a page is, the set held to the path rules and limits, and every relative reference
6
+ * looked up in the set. Errors are what certainly fails (`admitFiles` refuses them); the rest
7
+ * are warnings. Pure: any runtime.
8
+ */
9
+ /** A finding about one file of the set (`path`), or about the set as a whole. */
10
+ export interface FileFinding extends Omit<Finding, "rule"> {
11
+ readonly rule: Finding["rule"] | "files" | "missing-file" | "root-path" | "file-type";
12
+ readonly path?: string;
13
+ }
14
+ /** A set's files, by path: text, or bytes. */
15
+ export type FileContents = Readonly<Record<string, string | Uint8Array>>;
16
+ /**
17
+ * Lints a page that comes with files (P081): the set (paths, limits, its entry), each page as
18
+ * `lintContent` lints a page, each relative reference looked up in the set (a leading `/`, which
19
+ * names the address's root rather than the version, is an error in a page's markup), and each
20
+ * file whose extension the server doesn't know (a download).
21
+ */
22
+ export declare function lintFiles(config: PortholeConfig, files: FileContents, options?: {
23
+ readonly entry?: string;
24
+ }): FileFinding[];
25
+ /** Where a finding is, for the agent: `about.html line 3: `. */
26
+ export declare const whereOf: (finding: FileFinding) => string;
@@ -0,0 +1,307 @@
1
+ import { checkFileSet, DEFAULT_ENTRY, fileLimits, lookupFile, servesFiles, } from "../files/paths.js";
2
+ import { fileTypeOf, knownType } from "../files/types.js";
3
+ import { sizeWords } from "../guide/limits.js";
4
+ import { lintContent } from "./lint.js";
5
+ /** A text's line numbers by offset: its line starts found once, each line then a binary search. */
6
+ function linesOf(text) {
7
+ const starts = [0];
8
+ for (let at = text.indexOf("\n"); at >= 0; at = text.indexOf("\n", at + 1)) {
9
+ starts.push(at + 1);
10
+ }
11
+ return (index) => {
12
+ let low = 0;
13
+ let high = starts.length - 1;
14
+ while (low < high) {
15
+ const middle = (low + high + 1) >> 1;
16
+ if ((starts[middle] ?? 0) <= index) {
17
+ low = middle;
18
+ }
19
+ else {
20
+ high = middle - 1;
21
+ }
22
+ }
23
+ return low + 1;
24
+ };
25
+ }
26
+ const textOf = (body) => typeof body === "string" ? body : new TextDecoder().decode(body);
27
+ const sizeOf = (body) => typeof body === "string" ? new TextEncoder().encode(body).byteLength : body.byteLength;
28
+ /** How much of one file the references are looked for in: its first 2 MiB of text. */
29
+ const SCANNED = 2 * 1024 * 1024;
30
+ /** The most references of one kind looked up in one file: past that, a file is only linted. */
31
+ const MOST_REFERENCES = 2_000;
32
+ /** The elements whose attribute names a file the page loads or links: which attribute. */
33
+ const REFERENCE_ATTRIBUTES = {
34
+ script: ["src"],
35
+ img: ["src"],
36
+ source: ["src"],
37
+ video: ["src", "poster"],
38
+ audio: ["src"],
39
+ track: ["src"],
40
+ embed: ["src"],
41
+ input: ["src"],
42
+ link: ["href"],
43
+ a: ["href"],
44
+ area: ["href"],
45
+ };
46
+ /** A tag: its name and its attributes' text. Bounded, and never across another `<`: linear. */
47
+ const TAG = /<([a-z][a-z0-9-]{0,30})\b([^<>]{0,8192})>/giu;
48
+ const isSpace = (code) => code === 32 || code === 9 || code === 10 || code === 12 || code === 13;
49
+ /** A tag's attributes, read once from left to right (linear): each name, value and its offset. */
50
+ function attributesOf(text) {
51
+ const out = [];
52
+ let at = 0;
53
+ while (at < text.length) {
54
+ while (at < text.length && (isSpace(text.charCodeAt(at)) || text[at] === "/")) {
55
+ at += 1;
56
+ }
57
+ const nameStart = at;
58
+ while (at < text.length &&
59
+ !isSpace(text.charCodeAt(at)) &&
60
+ text[at] !== "=" &&
61
+ text[at] !== "/") {
62
+ at += 1;
63
+ }
64
+ const name = text.slice(nameStart, at).toLowerCase();
65
+ if (name === "") {
66
+ at += 1;
67
+ continue;
68
+ }
69
+ while (at < text.length && isSpace(text.charCodeAt(at))) {
70
+ at += 1;
71
+ }
72
+ if (text[at] !== "=") {
73
+ continue;
74
+ }
75
+ at += 1;
76
+ while (at < text.length && isSpace(text.charCodeAt(at))) {
77
+ at += 1;
78
+ }
79
+ const quote = text[at];
80
+ if (quote === '"' || quote === "'") {
81
+ const close = text.indexOf(quote, at + 1);
82
+ const end = close < 0 ? text.length : close;
83
+ out.push({ name, value: text.slice(at + 1, end), at: at + 1 });
84
+ at = end + 1;
85
+ }
86
+ else {
87
+ const start = at;
88
+ while (at < text.length && !isSpace(text.charCodeAt(at))) {
89
+ at += 1;
90
+ }
91
+ out.push({ name, value: text.slice(start, at), at: start });
92
+ }
93
+ }
94
+ return out;
95
+ }
96
+ /** What a page's markup loads or links: each element's `src`, `href` or `poster`. */
97
+ function markupReferences(text) {
98
+ const found = [];
99
+ for (const tag of text.matchAll(TAG)) {
100
+ if (found.length >= MOST_REFERENCES) {
101
+ break;
102
+ }
103
+ const name = (tag[1] ?? "").toLowerCase();
104
+ const wanted = Object.hasOwn(REFERENCE_ATTRIBUTES, name)
105
+ ? REFERENCE_ATTRIBUTES[name]
106
+ : undefined;
107
+ if (wanted === undefined) {
108
+ continue;
109
+ }
110
+ const offset = tag.index + 1 + name.length;
111
+ for (const attribute of attributesOf(tag[2] ?? "")) {
112
+ if (wanted.includes(attribute.name) && attribute.value !== "") {
113
+ found.push({ reference: attribute.value, index: offset + attribute.at });
114
+ }
115
+ }
116
+ }
117
+ return found;
118
+ }
119
+ /**
120
+ * The references a text's patterns find (group 2 of each). Every pattern is bounded and stops at
121
+ * its own delimiters, so a text is read in linear time, however it was written.
122
+ */
123
+ function patternReferences(text, patterns) {
124
+ const found = [];
125
+ for (const pattern of patterns) {
126
+ let count = 0;
127
+ for (const match of text.matchAll(pattern)) {
128
+ found.push({ reference: match[2] ?? "", index: match.index });
129
+ count += 1;
130
+ if (count >= MOST_REFERENCES) {
131
+ break;
132
+ }
133
+ }
134
+ }
135
+ return found;
136
+ }
137
+ const CSS_REFERENCES = [
138
+ /url\(\s{0,64}(["']?)([^"'()\s]{1,2048})\1\s{0,64}\)/giu,
139
+ /@import\s{1,64}(["'])([^"'\n]{1,2048})\1/giu,
140
+ ];
141
+ /** In a script: what resolves from the module (imports, `new URL(…, import.meta.url)`). */
142
+ const MODULE_REFERENCES = [
143
+ /\bfrom\s{0,64}(["'])(\.{1,2}\/[^"'\n]{0,2048})\1/gu,
144
+ /\bimport\s{0,64}\(?\s{0,64}(["'])(\.{1,2}\/[^"'\n]{0,2048})\1/gu,
145
+ /\bnew\s{1,64}URL\s{0,64}\(\s{0,64}(["'])([^"'\n]{1,2048})\1\s{0,64},\s{0,64}import\.meta\.url\b/gu,
146
+ ];
147
+ /** In a script: what resolves from the page (fetches, workers made from a string). */
148
+ const PAGE_REFERENCES = [
149
+ /\bfetch\s{0,64}\(\s{0,64}(["'`])(\.{0,2}\/?[\w./-][^"'`$\n]{0,2048})\1/gu,
150
+ /\bnew\s{1,64}(?:Shared)?Worker\s{0,64}\(\s{0,64}(["'`])([^"'`$\n]{1,2048})\1/gu,
151
+ ];
152
+ /** Whether a reference leaves the set for good reason: another origin, inline data, an anchor. */
153
+ const elsewhere = (reference) => /^[a-z][a-z0-9+.-]*:/iu.test(reference) ||
154
+ reference.startsWith("//") ||
155
+ reference.startsWith("#");
156
+ /** `reference` from a file in `directory` ("" or "a/b/"), as a path of the set; null above it. */
157
+ function resolve(directory, reference) {
158
+ const bare = reference.split("#")[0]?.split("?")[0] ?? "";
159
+ let decoded;
160
+ try {
161
+ decoded = decodeURIComponent(bare);
162
+ }
163
+ catch {
164
+ decoded = bare;
165
+ }
166
+ const segments = `${directory}${decoded}`.split("/");
167
+ const out = [];
168
+ for (const [index, segment] of segments.entries()) {
169
+ if (segment === "..") {
170
+ if (out.length === 0) {
171
+ return null;
172
+ }
173
+ out.pop();
174
+ }
175
+ else if (segment !== "." && (segment !== "" || index === segments.length - 1)) {
176
+ out.push(segment);
177
+ }
178
+ }
179
+ return out.join("/");
180
+ }
181
+ const directoryOf = (path) => path.slice(0, path.lastIndexOf("/") + 1);
182
+ /**
183
+ * Lints a page that comes with files (P081): the set (paths, limits, its entry), each page as
184
+ * `lintContent` lints a page, each relative reference looked up in the set (a leading `/`, which
185
+ * names the address's root rather than the version, is an error in a page's markup), and each
186
+ * file whose extension the server doesn't know (a download).
187
+ */
188
+ export function lintFiles(config, files, options = {}) {
189
+ const findings = [];
190
+ if (!servesFiles(config)) {
191
+ findings.push({
192
+ rule: "files",
193
+ severity: "error",
194
+ message: "A page here is one document: it can't come with files. Put its styles, scripts and data in the page itself.",
195
+ });
196
+ return findings;
197
+ }
198
+ const entry = options.entry ?? DEFAULT_ENTRY;
199
+ const sized = Object.fromEntries(Object.entries(files).map(([path, body]) => [path, { size: sizeOf(body) }]));
200
+ const problems = checkFileSet(sized, { entry, limits: fileLimits(config.limits) });
201
+ for (const problem of problems) {
202
+ findings.push({
203
+ rule: "files",
204
+ severity: "error",
205
+ message: `${problem.message}.`,
206
+ ...(problem.path === undefined ? {} : { path: problem.path }),
207
+ });
208
+ }
209
+ // Over the limits, the version isn't taken: nothing in it is read.
210
+ if (problems.some((each) => each.code === "count" || each.code === "size" || each.code === "total")) {
211
+ return findings;
212
+ }
213
+ const has = (path) => Object.hasOwn(files, path);
214
+ const found = (path) => lookupFile(has, path, { entry, navigation: false }).kind !== "none";
215
+ const reported = new Set();
216
+ const check = (from, lineOf, references, directory, rooted, also) => {
217
+ const seen = new Set();
218
+ for (const { reference, index } of references) {
219
+ if (seen.has(reference)) {
220
+ continue;
221
+ }
222
+ seen.add(reference);
223
+ if (reference === "" || elsewhere(reference) || reference.includes("${")) {
224
+ continue;
225
+ }
226
+ if (reference.startsWith("/")) {
227
+ const key = `${from} / ${reference}`;
228
+ if (!reported.has(key)) {
229
+ reported.add(key);
230
+ findings.push({
231
+ rule: "root-path",
232
+ severity: rooted,
233
+ message: `${reference} starts with /: that is the address's root, not this version's files. Write it relative (.${reference})${reference.startsWith("/assets/") ? '; for a Vite build, set base: "./"' : ""}.`,
234
+ path: from,
235
+ line: lineOf(index),
236
+ });
237
+ }
238
+ continue;
239
+ }
240
+ const target = resolve(directory, reference);
241
+ const other = also === undefined ? null : resolve(also, reference);
242
+ const named = (target !== null && found(target)) || (other !== null && found(other));
243
+ const key = `${from} ${target ?? reference}`;
244
+ if (!named && !reported.has(key)) {
245
+ reported.add(key);
246
+ findings.push({
247
+ rule: "missing-file",
248
+ severity: "warning",
249
+ message: target === null && other === null
250
+ ? `${reference} goes above the version's own files: nothing is there.`
251
+ : `${reference} names ${(target ?? other) === "" ? "the version's entry" : (target ?? other)}, which isn't one of the files.`,
252
+ path: from,
253
+ line: lineOf(index),
254
+ });
255
+ }
256
+ }
257
+ };
258
+ const maxPage = config.limits.maxBytes;
259
+ for (const [path, body] of Object.entries(files)) {
260
+ const { role } = fileTypeOf(path);
261
+ if (!knownType(path)) {
262
+ findings.push({
263
+ rule: "file-type",
264
+ severity: "warning",
265
+ message: `${path} is served as a download: its extension isn't one the server knows.`,
266
+ path,
267
+ });
268
+ }
269
+ const directory = directoryOf(path);
270
+ if (role === "page") {
271
+ const bytes = sizeOf(body);
272
+ if (bytes > maxPage) {
273
+ // Over the page's limit: said, and not read further.
274
+ findings.push({
275
+ rule: "size",
276
+ severity: "error",
277
+ message: `It is ${sizeWords(bytes)}; a page may be at most ${sizeWords(maxPage)}: move what it holds into files of its own (scripts, styles, data).`,
278
+ path,
279
+ });
280
+ continue;
281
+ }
282
+ const text = textOf(body);
283
+ for (const finding of lintContent(config, text)) {
284
+ findings.push({ ...finding, path });
285
+ }
286
+ const lines = linesOf(text);
287
+ check(path, lines, markupReferences(text), directory, "error");
288
+ check(path, lines, patternReferences(text, CSS_REFERENCES), directory, "warning");
289
+ check(path, lines, patternReferences(text, [...MODULE_REFERENCES, ...PAGE_REFERENCES]), directory, "warning");
290
+ }
291
+ else if (path.endsWith(".css")) {
292
+ const text = textOf(body).slice(0, SCANNED);
293
+ check(path, linesOf(text), patternReferences(text, CSS_REFERENCES), directory, "warning");
294
+ }
295
+ else if (role === "script") {
296
+ const text = textOf(body).slice(0, SCANNED);
297
+ const lines = linesOf(text);
298
+ check(path, lines, patternReferences(text, MODULE_REFERENCES), directory, "warning");
299
+ // A fetch from a script resolves from the page that runs it: the entry's directory, or the
300
+ // script's own (a worker's).
301
+ check(path, lines, patternReferences(text, PAGE_REFERENCES), directoryOf(entry), "warning", directory);
302
+ }
303
+ }
304
+ return findings;
305
+ }
306
+ /** Where a finding is, for the agent: `about.html line 3: `. */
307
+ export const whereOf = (finding) => `${finding.path === undefined ? "" : finding.path}${finding.line === undefined ? "" : `${finding.path === undefined ? "" : " "}line ${finding.line}`}${finding.path === undefined && finding.line === undefined ? "" : ": "}`;
@@ -1,3 +1,4 @@
1
+ import type { PageDeclaration } from "../runtime/declaration.ts";
1
2
  import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
2
3
  import type { InstanceRef } from "../isolation/types.ts";
3
4
  /**
@@ -12,6 +13,8 @@ export interface CheckRunSpec {
12
13
  readonly scriptLines: readonly number[];
13
14
  /** A served config's instance (located through the check's own server), else opaque. */
14
15
  readonly instance?: InstanceRef;
16
+ /** Under a runtime: the page's declaration (null: none). */
17
+ readonly declaration?: PageDeclaration | null;
15
18
  readonly widthPx: number;
16
19
  readonly heightPx?: number;
17
20
  readonly scheme: ColorScheme;
@@ -21,22 +21,39 @@ export function fragmentOf(content) {
21
21
  .replace(/<head[^>]*>[\s\S]*?<\/head>/iu, "");
22
22
  return body.trim() === "" ? null : `${kept}${kept === "" ? "" : "\n"}${body.trim()}`;
23
23
  }
24
- /** Where content reaches out, by the kind of egress each would need. */
24
+ /**
25
+ * Where content reaches out, by the kind of egress each would need. Each pattern is bounded and
26
+ * never runs past its own delimiters (a tag's `<`, a string's quote), so a text is read in linear
27
+ * time however it was written.
28
+ */
25
29
  const REACHES = [
26
- { kind: "script", pattern: /<script\b[^>]*\bsrc\s*=\s*["']?(https?:\/\/[^"'\s>]+)/giu },
27
- { kind: "script", pattern: /\bimport\s*(?:[\w{}\s*,]+from\s*)?\(?\s*["'](https?:\/\/[^"']+)/gu },
28
- { kind: "style", pattern: /<link\b[^>]*\bhref\s*=\s*["']?(https?:\/\/[^"'\s>]+)/giu },
29
- { kind: "style", pattern: /@import\s+(?:url\()?["']?(https?:\/\/[^"')\s]+)/giu },
30
- { kind: "img", pattern: /<img\b[^>]*\bsrc\s*=\s*["']?(https?:\/\/[^"'\s>]+)/giu },
31
- { kind: "img", pattern: /url\(\s*["']?(https?:\/\/[^"')\s]+)/giu },
30
+ {
31
+ kind: "script",
32
+ pattern: /<script\b[^<>]{0,8192}?\bsrc\s{0,64}=\s{0,64}["']?(https?:\/\/[^"'\s<>]{1,2048})/giu,
33
+ },
34
+ { kind: "script", pattern: /\bfrom\s{0,64}["'](https?:\/\/[^"'\n]{1,2048})/gu },
35
+ { kind: "script", pattern: /\bimport\s{0,64}\(?\s{0,64}["'](https?:\/\/[^"'\n]{1,2048})/gu },
36
+ {
37
+ kind: "style",
38
+ pattern: /<link\b[^<>]{0,8192}?\bhref\s{0,64}=\s{0,64}["']?(https?:\/\/[^"'\s<>]{1,2048})/giu,
39
+ },
40
+ {
41
+ kind: "style",
42
+ pattern: /@import\s{1,64}(?:url\()?["']?(https?:\/\/[^"')\s]{1,2048})/giu,
43
+ },
44
+ {
45
+ kind: "img",
46
+ pattern: /<img\b[^<>]{0,8192}?\bsrc\s{0,64}=\s{0,64}["']?(https?:\/\/[^"'\s<>]{1,2048})/giu,
47
+ },
48
+ { kind: "img", pattern: /url\(\s{0,64}["']?(https?:\/\/[^"')\s]{1,2048})/giu },
32
49
  {
33
50
  kind: "media",
34
- pattern: /<(?:video|audio|source)\b[^>]*\bsrc\s*=\s*["']?(https?:\/\/[^"'\s>]+)/giu,
51
+ pattern: /<(?:video|audio|source)\b[^<>]{0,8192}?\bsrc\s{0,64}=\s{0,64}["']?(https?:\/\/[^"'\s<>]{1,2048})/giu,
35
52
  },
36
- { kind: "connect", pattern: /\bfetch\s*\(\s*["'`](https?:\/\/[^"'`]+)/gu },
53
+ { kind: "connect", pattern: /\bfetch\s{0,64}\(\s{0,64}["'`](https?:\/\/[^"'`\n]{1,2048})/gu },
37
54
  {
38
55
  kind: "connect",
39
- pattern: /\bnew\s+(?:WebSocket|EventSource)\s*\(\s*["'`]((?:https?|wss?):\/\/[^"'`]+)/gu,
56
+ pattern: /\bnew\s{1,64}(?:WebSocket|EventSource)\s{0,64}\(\s{0,64}["'`]((?:https?|wss?):\/\/[^"'`\n]{1,2048})/gu,
40
57
  },
41
58
  ];
42
59
  const CDN_PACKAGE = /^https:\/\/(?:cdn\.jsdelivr\.net\/npm|unpkg\.com|esm\.sh)\/((?:@[^/]+\/)?[^/@]+)(@[^/]*)?/u;
@@ -92,7 +109,9 @@ export function lintContent(config, content) {
92
109
  const clipboard = /\bnavigator\s*\.\s*clipboard\b|\bexecCommand\s*\(\s*["'](?:copy|cut)["']/u.exec(content);
93
110
  if (clipboard !== null) {
94
111
  add("clipboard", "warning", declared.has("copyText")
95
- ? "The clipboard is closed to content: a copy button calls copyText(text) from its click."
112
+ ? config.runtime === undefined
113
+ ? "The clipboard is closed to content: a copy button calls copyText(text) from its click."
114
+ : 'The clipboard is closed to content: a copy button calls (await porthole.use("clipboard")).copy(text) from its click.'
96
115
  : "The clipboard is closed to content: copying from a button doesn't work here.", clipboard.index);
97
116
  }
98
117
  const dialog = /(?:^|[^.\w$])(?:window\s*\.\s*)?(alert|confirm|prompt)\s*\(/u.exec(content);
@@ -122,7 +141,7 @@ export function lintContent(config, content) {
122
141
  egressOrigins(config, kind).some((source) => source === origin || originMatchesSource(origin, source));
123
142
  if (!open && !reported.has(`${kind} ${origin}`)) {
124
143
  reported.add(`${kind} ${origin}`);
125
- add("egress", "warning", `Nothing loads from ${origin} here (${kind}): ${kind === "script" && librarySources(config).length > 0 ? "write it inline, or use one of the libraries served here (the manual's Libraries)" : kind === "script" || kind === "style" ? "write it inline, or use a library from an allowed CDN" : kind === "connect" && config.capabilities.readData !== undefined ? "the content can't call it; read the app's data with readData" : kind === "connect" ? "the content can't call it; work from data in the content" : "put it inline as a data: URL"}.`, match.index);
144
+ add("egress", "warning", `Nothing loads from ${origin} here (${kind}): ${kind === "script" && librarySources(config).length > 0 ? "write it inline, or use one of the libraries served here (the manual's Libraries)" : kind === "script" || kind === "style" ? "write it inline, or use a library from an allowed CDN" : kind === "connect" && config.capabilities.readData !== undefined ? `the content can't call it; read the app's data with ${config.runtime === undefined ? "readData" : "data.read"}` : kind === "connect" ? "the content can't call it; work from data in the content" : "put it inline as a data: URL"}.`, match.index);
126
145
  }
127
146
  const own = OWN_CDN.find((each) => each.host.test(address));
128
147
  if (own !== undefined && kind === "script" && !own.pinned.test(new URL(address).pathname)) {