@runeditrun/rer 0.2.74 → 0.2.76

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 (66) hide show
  1. package/README.md +7 -2
  2. package/cli/export.mjs +1 -1
  3. package/cli/listing.mjs +20 -0
  4. package/cli/main.mjs +1 -0
  5. package/cli/parse.mjs +2 -1
  6. package/cli/portability-migrations.mjs +46 -0
  7. package/cli/portability-worker.mjs +7 -20
  8. package/cli/portability.mjs +5 -4
  9. package/cli/server-registry.mjs +43 -18
  10. package/cli/server-resources.mjs +38 -9
  11. package/cli/site-check.mjs +4 -2
  12. package/cli/site-prepare.mjs +6 -0
  13. package/cli/site-render.mjs +7 -1
  14. package/cli/site-runtime.mjs +55 -0
  15. package/cli/site.mjs +45 -17
  16. package/global/CHANGELOG.md +13 -0
  17. package/global/README.md +7 -2
  18. package/global/launch/state.mjs +5 -4
  19. package/global/launch/stop.mjs +30 -8
  20. package/global/main.mjs +2 -1
  21. package/modules/deploy-kit/README.md +47 -2
  22. package/modules/deploy-kit/owner-cli.mjs +2 -1
  23. package/modules/deploy-kit/site-readback.mjs +12 -2
  24. package/modules/deploy-kit/site-runtime.mjs +33 -0
  25. package/modules/deploy-kit/site.mjs +27 -8
  26. package/modules/job-queue/command.mjs +8 -3
  27. package/modules/portability/README.md +40 -11
  28. package/modules/portability/backfills.mjs +29 -16
  29. package/modules/portability/bridge.mjs +24 -29
  30. package/modules/portability/import.mjs +1 -2
  31. package/modules/portability/index.d.mts +1 -1
  32. package/modules/portability/ledgers.mjs +22 -0
  33. package/modules/portability/migration-history.mjs +2 -2
  34. package/modules/release/README.md +135 -3
  35. package/modules/release/catalogue.mjs +6 -2
  36. package/modules/release/listing.mjs +64 -0
  37. package/modules/release/look.mjs +26 -0
  38. package/modules/release/previous-listing.mjs +44 -0
  39. package/modules/release/produce.mjs +3 -0
  40. package/modules/release/screenshots.mjs +51 -0
  41. package/modules/release/signature.mjs +3 -2
  42. package/modules/release/source.mjs +19 -6
  43. package/modules/release/statement.mjs +8 -4
  44. package/modules/site/docs-search/SearchField.tsx +18 -0
  45. package/modules/site/docs-search/artifacts.mjs +54 -0
  46. package/modules/site/docs-search/client.ts +194 -0
  47. package/modules/site/docs-search/index-build.mjs +63 -0
  48. package/modules/site/docs-search/retrieve.ts +16 -0
  49. package/modules/site/docs-search/search.css +19 -0
  50. package/modules/site/docs-search/sections.ts +24 -0
  51. package/modules/site/docs-search/types.ts +14 -0
  52. package/modules/site/docs-search/worker.ts +39 -0
  53. package/onboarding/process-cleanup.mjs +5 -5
  54. package/onboarding/process-scope.mjs +1 -1
  55. package/onboarding/process-table.mjs +6 -4
  56. package/onboarding/process-tree.mjs +4 -4
  57. package/onboarding/schema/json-schema.mjs +4 -1
  58. package/package.json +1 -1
  59. package/scripts/publish-check/README.md +14 -0
  60. package/scripts/publish-check/assignment.py +48 -0
  61. package/scripts/publish-check/credential_assignments.mjs +75 -0
  62. package/scripts/publish-check/credential_assignments.py +70 -0
  63. package/scripts/publish-check/credential_literals.mjs +66 -0
  64. package/scripts/publish-check/credential_syntax.mjs +29 -0
  65. package/scripts/publish-check/env_values.py +14 -1
  66. package/scripts/publish-check/history_scan.py +9 -2
@@ -0,0 +1,26 @@
1
+ import { createHash } from 'node:crypto';
2
+ import { matchesGlob } from 'node:path';
3
+
4
+ export const defaultLook = Object.freeze({
5
+ home: ['public/brand/**', 'src/branding.json', 'public/rer-theme.css', 'public/fonts/**', 'src/site/**', '!src/site/docs/**'],
6
+ app: ['public/brand/**', 'src/branding.json', 'public/**/*.{css,js,mjs,html}', 'src/ui/**', 'src/**/*.css', 'src/client/**'],
7
+ });
8
+
9
+ export function lookFingerprints(source) {
10
+ const declared = source.entries.has('rer-project.json') ? JSON.parse(source.bytes('rer-project.json')).look : undefined;
11
+ if (declared !== undefined && (!declared || typeof declared !== 'object' || Array.isArray(declared) || Object.keys(declared).some(key => !['home', 'app'].includes(key))))
12
+ throw Error('rer-project.json look must declare home and/or app glob arrays');
13
+ return Object.fromEntries(['home', 'app'].map(kind => {
14
+ const globs = declared?.[kind] ?? defaultLook[kind];
15
+ if (!Array.isArray(globs) || !globs.every(glob => typeof glob === 'string' && glob.replace(/^!/, '') && !/[\\\0\r\n]/.test(glob) && !glob.replace(/^!/, '').startsWith('/') && !glob.split('/').includes('..')))
16
+ throw Error('Look globs must be repository-relative patterns');
17
+ const includes = globs.filter(glob => !glob.startsWith('!')), excludes = globs.filter(glob => glob.startsWith('!')).map(glob => glob.slice(1));
18
+ const hash = createHash('sha256');
19
+ for (const path of [...source.entries.keys()].sort()) {
20
+ const entry = source.entries.get(path);
21
+ if (entry.type === 'blob' && includes.some(glob => matchesGlob(path, glob)) && !excludes.some(glob => matchesGlob(path, glob)))
22
+ hash.update(`${path}\0${entry.oid}\n`);
23
+ }
24
+ return [kind, `sha256:${hash.digest('hex')}`];
25
+ }));
26
+ }
@@ -0,0 +1,44 @@
1
+ import { committedSource, git } from './source.mjs';
2
+ import { listingContent } from './listing.mjs';
3
+
4
+ const order = (a, b) => a === b ? 0 : a < b ? -1 : 1;
5
+ function version(value) {
6
+ const match = /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?$/.exec(value);
7
+ return match ? { core: match.slice(1, 4).map(BigInt), pre: match[4]?.split('.') ?? [] } : null;
8
+ }
9
+ function compare(a, b) {
10
+ for (let i = 0; i < 3; i++) if (a.core[i] !== b.core[i]) return order(a.core[i], b.core[i]);
11
+ if (!a.pre.length || !b.pre.length) return order(Boolean(b.pre.length), Boolean(a.pre.length));
12
+ for (let i = 0; i < Math.max(a.pre.length, b.pre.length); i++) {
13
+ const x = a.pre[i], y = b.pre[i];
14
+ if (x === undefined || y === undefined) return order(a.pre.length, b.pre.length);
15
+ if (x === y) continue;
16
+ const nx = /^\d+$/.test(x), ny = /^\d+$/.test(y);
17
+ return nx && ny ? order(BigInt(x), BigInt(y)) : nx !== ny ? (nx ? -1 : 1) : order(x, y);
18
+ }
19
+ return 0;
20
+ }
21
+
22
+ // Only advertised tags count. A scratch/local tag can never claim that stale
23
+ // pictures were public. The selected ref's own release tag is excluded.
24
+ export function previousListing(source, repository) {
25
+ if (!source.repo || !git(source.repo, 'remote').toString().split('\n').includes('origin')) return null;
26
+ const origin = git(source.repo, 'remote', 'get-url', 'origin').toString().trim();
27
+ const remote = /^(?:https:\/\/github\.com\/|git@github\.com:)/.test(origin) ? repository : origin;
28
+ const current = version(source.seed.version);
29
+ if (!current) return null;
30
+ const records = git(source.repo, 'ls-remote', '--tags', remote, 'refs/tags/v*').toString().trim().split('\n').filter(Boolean);
31
+ const refs = new Map(records.map(record => record.split('\t').reverse()));
32
+ const tags = [...refs].filter(([ref]) => !ref.endsWith('^{}')).map(([ref, oid]) => ({ ref, oid, commit: refs.get(ref + '^{}') ?? oid, version: version(ref.slice('refs/tags/'.length)) }))
33
+ .filter(tag => tag.version && compare(tag.version, current) <= 0 && tag.commit !== source.commit)
34
+ .sort((a, b) => compare(a.version, b.version));
35
+ let previous = null;
36
+ for (const tag of tags) {
37
+ // Fetch the advertised object by ID, without changing local tag refs.
38
+ try { git(source.repo, 'cat-file', '-e', `${tag.commit}^{commit}`); }
39
+ catch { git(source.repo, 'fetch', '--no-tags', '--filter=blob:none', remote, tag.oid); }
40
+ const prior = committedSource(source.repo, tag.commit, { hydrateFrom: remote });
41
+ previous = listingContent(prior, repository, previous);
42
+ }
43
+ return previous;
44
+ }
@@ -11,6 +11,8 @@ import { writePublishHandoff } from './publish-handoff.mjs';
11
11
  import { releasePublicBase } from './public-base.mjs';
12
12
  import { prepareTagAdoption, confirmTagAdoption, assertTagAdoption } from './tag-adoption.mjs';
13
13
  import { placeholderMarks, placeholderMessage } from '../../cli/placeholder-mark.mjs';
14
+ import { listingContent } from './listing.mjs';
15
+ import { previousListing } from './previous-listing.mjs';
14
16
  import { cleanupTemporary } from './cleanup.mjs';
15
17
  import { parseTimeoutSeconds } from '../../scripts/publish-check/timeout.mjs';
16
18
 
@@ -37,6 +39,7 @@ export async function release({ repo, ref = 'HEAD', output, project, repository,
37
39
  if (typeof tag === 'string' && tag !== source.tag) throw Error('Requested tag must match the committed release version');
38
40
  const existing = git(source.repo, 'tag', '--list', source.tag).toString().trim();
39
41
  if (existing && tag && !dryRun && (onto !== undefined || clean)) throw Error('Release tag already exists; choose a new committed version');
42
+ source.listingContent = listingContent(source, repository, previousListing(source, repository));
40
43
  // Validate metadata before installs or output writes.
41
44
  catalogue(source, project, repository, { verify: { status: 'PENDING' }, publishCheck: { status: 'PENDING' } }, preview);
42
45
  const destination = onto !== undefined ? publicDestination(onto, repository, source.repo) : null;
@@ -0,0 +1,51 @@
1
+ import { basename } from 'node:path';
2
+ import { createHash } from 'node:crypto';
3
+ import { validRelativePath } from './signature.mjs';
4
+
5
+ // Inspect the WebP container and encoded image dimensions, not its extension or
6
+ // the author's width/height claim. No image decoder or browser is required.
7
+ function webpSize(bytes) {
8
+ if (bytes.length < 20 || bytes.toString('ascii', 0, 4) !== 'RIFF' || bytes.toString('ascii', 8, 12) !== 'WEBP' || bytes.readUInt32LE(4) + 8 !== bytes.length)
9
+ throw Error('Screenshot must be a complete WebP image');
10
+ let canvas, image;
11
+ for (let offset = 12; offset < bytes.length;) {
12
+ if (offset + 8 > bytes.length) throw Error('Invalid WebP chunk');
13
+ const type = bytes.toString('ascii', offset, offset + 4), size = bytes.readUInt32LE(offset + 4), start = offset + 8;
14
+ if (start + size + (size & 1) > bytes.length) throw Error('Invalid WebP chunk length');
15
+ if (type === 'VP8X' && size === 10) {
16
+ if (bytes[start] & 2) throw Error('Screenshot WebP must be a still image');
17
+ canvas = [1 + bytes.readUIntLE(start + 4, 3), 1 + bytes.readUIntLE(start + 7, 3)];
18
+ } else if (type === 'VP8 ' && size >= 10 && bytes.subarray(start + 3, start + 6).equals(Buffer.from([0x9d, 0x01, 0x2a]))) {
19
+ image = [bytes.readUInt16LE(start + 6) & 0x3fff, bytes.readUInt16LE(start + 8) & 0x3fff];
20
+ } else if (type === 'VP8L' && size >= 5 && bytes[start] === 0x2f) {
21
+ const bits = bytes.readUInt32LE(start + 1);
22
+ image = [(bits & 0x3fff) + 1, ((bits >>> 14) & 0x3fff) + 1];
23
+ }
24
+ offset = start + size + (size & 1);
25
+ }
26
+ if (!image || (canvas && (canvas[0] !== image[0] || canvas[1] !== image[1]))) throw Error('Invalid WebP image dimensions');
27
+ return image;
28
+ }
29
+
30
+ export function screenshotSet(source, id) {
31
+ const screenshots = source.release?.screenshots;
32
+ if (screenshots === undefined) return { shots: [], assets: [], identity: null };
33
+ if (!Array.isArray(screenshots) || screenshots.length < 1 || screenshots.length > 5) throw Error('RELEASE.json screenshots requires 1–5 images');
34
+ const paths = new Set(), assets = [];
35
+ const shots = screenshots.map(shot => {
36
+ if (!validRelativePath(shot?.path) || !shot.path.endsWith('.webp') || !['alt', 'caption'].every(key => typeof shot[key] === 'string' && shot[key].trim()) || shot.width !== 1600 || shot.height !== 1000)
37
+ throw Error('Each screenshot needs a WebP path, alt, caption, width 1600 and height 1000');
38
+ const bytes = source.bytes(shot.path), [width, height] = webpSize(bytes);
39
+ if (width !== 1600 || height !== 1000 || bytes.length > 300 * 1024) throw Error('Screenshot WebP must be 1600x1000 and at most 300 KiB');
40
+ const path = `assets/seeds/${id}/${basename(shot.path)}`;
41
+ if (paths.has(path) || ['mark.svg', 'mark-light.svg'].includes(basename(shot.path))) throw Error('Screenshot bundle paths must be unique');
42
+ paths.add(path); assets.push({ path, bytes });
43
+ return { path, alt: shot.alt, caption: shot.caption, width, height };
44
+ });
45
+ // Byte identity plus source names distinguish a recapture at the same path
46
+ // from unchanged pictures; copy edits alone cannot claim a fresh capture.
47
+ const identities = screenshots.map((shot, index) => [shot.path, createHash('sha256').update(assets[index].bytes).digest('hex')])
48
+ .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
49
+ const identity = createHash('sha256').update(JSON.stringify(identities)).digest('hex');
50
+ return { shots, assets, identity };
51
+ }
@@ -106,7 +106,7 @@ export function compareVersion(a, b) {
106
106
  return 0;
107
107
  }
108
108
  const requiredFiles = ['public-source.tar', 'release-receipt.json', 'publish-check.json'];
109
- const filePattern = /^(public-source\.tar|release-receipt\.json|publish-check\.json|site\/[a-z0-9]+(?:-[a-z0-9]+)*\/[^/]+\/(?:release\.json|documents\/.+))$/;
109
+ const filePattern = /^(public-source\.tar|release-receipt\.json|publish-check\.json|site\/[a-z0-9]+(?:-[a-z0-9]+)*\/[^/]+\/(?:release\.json|documents\/.+|assets\/seeds\/[a-z0-9]+(?:-[a-z0-9]+)*\/.+))$/;
110
110
  function safePath(path) {
111
111
  return validRelativePath(path) && matches(path, filePattern);
112
112
  }
@@ -131,7 +131,8 @@ export function validateStatement(s) {
131
131
  if (releases.length !== 1 || releases[0].path.split('/')[2] !== s.version) refuse('STATEMENT_INVALID');
132
132
  const prefix = releases[0].path.slice(0, -'release.json'.length);
133
133
  if (requiredFiles.some(path => !s.files.some(f => f.path === path))
134
- || s.files.some(f => f.path.startsWith('site/') && !f.path.startsWith(prefix))) refuse('STATEMENT_INVALID');
134
+ || s.files.some(f => f.path.startsWith('site/') && (!f.path.startsWith(prefix)
135
+ || (f.path.startsWith(prefix + 'assets/') && !f.path.startsWith(prefix + `assets/seeds/${releases[0].path.split('/')[1]}/`))))) refuse('STATEMENT_INVALID');
135
136
  } catch (error) { sanitized(error, 'STATEMENT_INVALID'); }
136
137
  }
137
138
  function parseJSON(value, code) {
@@ -17,9 +17,8 @@ export function git(repo, ...args) {
17
17
  } catch { throw Error('Git source operation failed'); }
18
18
  }
19
19
 
20
- export function inspectSource(repo, ref) {
20
+ export function committedSource(repo, ref, { hydrateFrom } = {}) {
21
21
  repo = realpathSync(repo);
22
- if (git(repo, 'status', '--porcelain', '--untracked-files=all').length) throw Error('Release requires a clean source checkout');
23
22
  const commit = git(repo, 'rev-parse', '--verify', '--end-of-options', `${ref}^{commit}`).toString().trim();
24
23
  const tree = git(repo, 'rev-parse', `${commit}^{tree}`).toString().trim();
25
24
  const records = git(repo, 'ls-tree', '-r', '-z', commit).toString().split('\0').filter(Boolean);
@@ -33,15 +32,29 @@ export function inspectSource(repo, ref) {
33
32
  const bytes = path => {
34
33
  const entry = entries.get(path);
35
34
  if (!entry || entry.type !== 'blob' || !['100644', '100755'].includes(entry.mode)) throw Error('Release input must be a committed ordinary file');
35
+ if (hydrateFrom) {
36
+ try { git(repo, 'cat-file', '-e', entry.oid); }
37
+ catch { git(repo, 'fetch', '--no-tags', hydrateFrom, entry.oid); }
38
+ }
36
39
  return git(repo, 'cat-file', 'blob', entry.oid);
37
40
  };
38
41
  const seed = JSON.parse(bytes('seed.json'));
39
- const pkg = JSON.parse(bytes('package.json'));
40
- const release = JSON.parse(bytes('RELEASE.json'));
42
+ const release = entries.has('RELEASE.json') ? JSON.parse(bytes('RELEASE.json')) : {};
43
+ // Read this object alone: show/log may inspect unavailable parents in a
44
+ // shallow partial clone, even when only the timestamp was requested.
45
+ const committedAt = /^committer .* (\d+) [+-]\d{4}$/m.exec(git(repo, 'cat-file', 'commit', commit).toString())?.[1];
46
+ if (!committedAt) throw Error('Invalid Git commit timestamp');
47
+ const timestamp = new Date(Number(committedAt) * 1000).toISOString();
48
+ return { repo, commit, tree, entries, bytes, seed, release, timestamp, tag: `v${seed.version}` };
49
+ }
50
+
51
+ export function inspectSource(repo, ref) {
52
+ if (git(repo, 'status', '--porcelain', '--untracked-files=all').length) throw Error('Release requires a clean source checkout');
53
+ const source = committedSource(repo, ref), { seed, release } = source;
54
+ const pkg = JSON.parse(source.bytes('package.json'));
41
55
  if (!/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/.test(seed.version) ||
42
56
  pkg.version !== seed.version || release.version !== seed.version || !pkg.scripts?.verify) throw Error('Seed, package and release versions must agree, and verify must exist');
43
- const timestamp = git(repo, 'log', '-1', '--format=%cI', commit).toString().trim();
44
- return { repo, commit, tree, entries, bytes, seed, release, timestamp, tag: `v${seed.version}` };
57
+ return source;
45
58
  }
46
59
 
47
60
  export function newOutput(repo, output) {
@@ -18,6 +18,7 @@ export async function readArtifact(directory) {
18
18
  if (!pathOK(manifestPath) || !/^site\/[a-z0-9]+(?:-[a-z0-9]+)*\/(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\/release\.json$/.test(manifestPath)) refuse('PATH_UNSAFE');
19
19
  const base = posix.dirname(manifestPath);
20
20
  const selected = new Map();
21
+ const isAsset = path => path.startsWith(`${base}/assets/`);
21
22
  const walk = (relative = '') => {
22
23
  for (const name of readdirSync(resolve(root, relative)).sort()) {
23
24
  const path = relative ? `${relative}/${name}` : name;
@@ -32,9 +33,9 @@ export async function readArtifact(directory) {
32
33
  if (stat.isSymbolicLink() || (!stat.isDirectory() && !stat.isFile())) refuse('PATH_UNSAFE');
33
34
  if (stat.isFile() && stat.size > FILE_LIMIT) refuse('INPUT_TOO_LARGE');
34
35
  if (stat.isDirectory()) {
35
- if (!ancillary && path !== 'site' && path !== posix.dirname(base) && path !== base && path !== `${base}/documents` && !path.startsWith(`${base}/documents/`)) refuse('FILE_UNDECLARED');
36
+ if (!ancillary && path !== 'site' && path !== posix.dirname(base) && path !== base && path !== `${base}/documents` && !path.startsWith(`${base}/documents/`) && path !== `${base}/assets` && !isAsset(path)) refuse('FILE_UNDECLARED');
36
37
  walk(path);
37
- } else if (required.includes(path) || path === manifestPath || path.startsWith(`${base}/documents/`)) {
38
+ } else if (required.includes(path) || path === manifestPath || path.startsWith(`${base}/documents/`) || isAsset(path)) {
38
39
  selected.set(path, stat.size);
39
40
  if (selected.size > 256) refuse('INPUT_TOO_LARGE');
40
41
  } else if (!ancillary && !['PUBLISH.md', 'site/registry.json', SIGNATURE_FILE].includes(path)) refuse('FILE_UNDECLARED');
@@ -62,14 +63,17 @@ export async function readArtifact(directory) {
62
63
  if (!Array.isArray(manifest.artifacts)) refuse('STATEMENT_INVALID');
63
64
  const declared = new Set();
64
65
  for (const artifact of manifest.artifacts) {
65
- if (!pathOK(artifact?.path) || !artifact.path.startsWith('documents/')) refuse('PATH_UNSAFE');
66
+ if (!pathOK(artifact?.path) || !(artifact.path.startsWith('documents/') || artifact.path.startsWith(`assets/seeds/${manifest.listing.id}/`))) refuse('PATH_UNSAFE');
66
67
  const path = `${base}/${artifact.path}`;
67
68
  if (declared.has(path)) refuse('STATEMENT_INVALID');
68
69
  declared.add(path);
69
70
  if (!files.has(path)) refuse('FILE_MISSING');
70
71
  match(path, artifact.sha256);
71
72
  }
72
- for (const path of files.keys()) if (path.startsWith(`${base}/documents/`) && !declared.has(path)) refuse('FILE_UNDECLARED');
73
+ for (const path of files.keys()) if ((path.startsWith(`${base}/documents/`) || isAsset(path)) && !declared.has(path)) refuse('FILE_UNDECLARED');
74
+ for (const path of [manifest.listing.brand?.mark, manifest.listing.brand?.markLight, ...(manifest.listing.shots ?? []).map(shot => typeof shot === 'string' ? shot : shot.path)].filter(Boolean)) {
75
+ if (!pathOK(path) || !declared.has(`${base}/${path}`)) refuse('FILE_MISSING');
76
+ }
73
77
  return { root, receipt, subject, files, entries };
74
78
  }
75
79
 
@@ -0,0 +1,18 @@
1
+ import './search.css';
2
+
3
+ /** Static markup; the standalone site's client enhances each instance. */
4
+ export function SearchField({ id, endpoint = '/docs/search' }: { id: string; endpoint?: string }) {
5
+ return <div className="docs-search" data-docs-search data-endpoint={endpoint}>
6
+ <label className="docs-search-label" htmlFor={id}>Search docs</label>
7
+ <div className="docs-search-field">
8
+ <input id={id} type="search" placeholder="Search docs" autoComplete="off" spellCheck={false}
9
+ role="combobox" aria-autocomplete="list" aria-haspopup="listbox" aria-expanded="false"
10
+ aria-controls={`${id}-results`} aria-describedby={`${id}-status`} />
11
+ <kbd aria-hidden="true">/</kbd>
12
+ </div>
13
+ <div className="docs-search-panel" data-search-panel hidden>
14
+ <p id={`${id}-status`} className="docs-search-status" role="status" aria-live="polite" aria-atomic="true">Search the docs</p>
15
+ <ul id={`${id}-results`} className="docs-search-results" role="listbox" aria-label="Search results" hidden />
16
+ </div>
17
+ </div>;
18
+ }
@@ -0,0 +1,54 @@
1
+ import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
2
+ import { relative, resolve } from 'node:path';
3
+ import { fileURLToPath } from 'node:url';
4
+ import { createRequire } from 'node:module';
5
+ import { buildSearchIndex } from './index-build.mjs';
6
+
7
+ // The seed owns its build toolchain; rer remains dependency-free for offline launch.
8
+ const { build } = createRequire(resolve('package.json'))('esbuild');
9
+
10
+ /** Explicit credentialed build step. A failure stops publication; no lexical fallback. */
11
+ export async function buildSearchArtifacts({ corpus, assets, output, previousUrl, endpoint = '/docs/search', localName = 'docs-search-local', compatibilityDate = '2026-09-08' }, { embed, accountId } = {}) {
12
+ const pages = JSON.parse(await readFile(corpus, 'utf8'));
13
+ await mkdir(output, { recursive: true });
14
+ const indexPath = resolve(output, 'index.json');
15
+ const previous = [];
16
+ try { previous.push(JSON.parse(await readFile(indexPath, 'utf8'))); }
17
+ catch (error) { if (error.code !== 'ENOENT') throw error; }
18
+ if (previousUrl) {
19
+ const response = await fetch(previousUrl, { signal: AbortSignal.timeout(15000) });
20
+ if (response.status !== 404) {
21
+ if (!response.ok) throw Error(`Previous search artifact unavailable (${response.status}); build stopped.`);
22
+ previous.push(await response.json());
23
+ }
24
+ }
25
+ const remoteEmbed = async (model, input) => {
26
+ if (!process.env.CLOUDFLARE_API_TOKEN || !accountId) throw Error('Search indexing requires CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN (Workers AI Read).');
27
+ const response = await fetch(`https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/run/${model}`, {
28
+ method: 'POST', headers: { Authorization: `Bearer ${process.env.CLOUDFLARE_API_TOKEN}`, 'Content-Type': 'application/json' },
29
+ body: JSON.stringify(input), signal: AbortSignal.timeout(60000),
30
+ });
31
+ if (!response.ok) throw Error(`Workers AI embedding failed (${response.status}); build stopped.`);
32
+ const body = await response.json();
33
+ if (!body.success) throw Error('Workers AI refused embeddings; build stopped.');
34
+ return body.result;
35
+ };
36
+ const { index, counts } = await buildSearchIndex(pages, { previous, embed: embed ?? remoteEmbed,
37
+ onBatch: ({ embedded, total }) => console.log(`Docs search embeddings: ${embedded}/${total}`) });
38
+ const bytes = JSON.stringify(index);
39
+ await writeFile(`${indexPath}.new`, bytes);
40
+ await rename(`${indexPath}.new`, indexPath);
41
+ // Published with the same assets as the pages; the next clean deployment
42
+ // reuses these vectors by content hash, never a crawler or an update timer.
43
+ await writeFile(resolve(assets, 'docs-search-vectors.json'), bytes);
44
+ const runtime = fileURLToPath(new URL('./worker.ts', import.meta.url));
45
+ await build({ stdin: { contents: `import {createSearchWorker} from ${JSON.stringify(runtime)};export default createSearchWorker(${JSON.stringify({ endpoint, corpusHash: index.corpusHash })});`,
46
+ resolveDir: resolve(output), sourcefile: 'site-search-entry.ts', loader: 'ts' }, bundle: true, format: 'esm', platform: 'browser', target: 'es2022', outfile: resolve(output, 'worker.mjs') });
47
+ const configuration = { name: localName, main: './worker.mjs', compatibility_date: compatibilityDate,
48
+ ...(accountId ? { account_id: accountId } : {}), workers_dev: false,
49
+ assets: { directory: relative(resolve(output), resolve(assets)), binding: 'ASSETS', run_worker_first: true, html_handling: 'auto-trailing-slash', not_found_handling: '404-page' },
50
+ ai: { binding: 'AI', remote: true } };
51
+ await writeFile(resolve(output, 'wrangler.json'), `${JSON.stringify(configuration, null, 2)}\n`);
52
+ console.log(`Docs search: total=${counts.total} reused=${counts.reused} embedded=${counts.embedded} bytes=${Buffer.byteLength(bytes)}`);
53
+ return { index, counts };
54
+ }
@@ -0,0 +1,194 @@
1
+ type SearchResult = { href: string; titlePath: string[]; snippet: string; score: number };
2
+ const mounted = new WeakMap<HTMLElement, () => void>();
3
+
4
+ function readResults(payload: unknown): SearchResult[] {
5
+ if (!payload || typeof payload !== 'object' || !('results' in payload) || !Array.isArray(payload.results)) {
6
+ throw new Error('Invalid search response');
7
+ }
8
+ return payload.results.slice(0, 5).map((value: unknown) => {
9
+ if (!value || typeof value !== 'object' || !('href' in value) || typeof value.href !== 'string'
10
+ || !('titlePath' in value) || !Array.isArray(value.titlePath) || !value.titlePath.every((part: unknown) => typeof part === 'string')
11
+ || !('snippet' in value) || typeof value.snippet !== 'string'
12
+ || !('score' in value) || typeof value.score !== 'number' || !Number.isFinite(value.score)) {
13
+ throw new Error('Invalid search result');
14
+ }
15
+ const url = new URL(value.href, document.baseURI);
16
+ if (url.origin !== location.origin || !['http:', 'https:'].includes(url.protocol)) throw new Error('Invalid search link');
17
+ return { href: url.href, titlePath: value.titlePath, snippet: value.snippet, score: value.score };
18
+ });
19
+ }
20
+
21
+ function mount(root: HTMLElement): () => void {
22
+ const input = root.querySelector<HTMLInputElement>('input[type="search"]');
23
+ const panel = root.querySelector<HTMLElement>('[data-search-panel]');
24
+ const list = root.querySelector<HTMLUListElement>('[role="listbox"]');
25
+ const status = root.querySelector<HTMLElement>('[role="status"]');
26
+ if (!input || !panel || !list || !status) throw new Error('Incomplete docs search field');
27
+ const address = root.dataset.endpoint;
28
+ if (!address) throw new Error('Docs search endpoint is missing');
29
+ const baseEndpoint = new URL(address, document.baseURI);
30
+ const listeners = new AbortController();
31
+ let request: AbortController | undefined;
32
+ let timer: ReturnType<typeof setTimeout> | undefined;
33
+ let revision = 0;
34
+ let links: HTMLAnchorElement[] = [];
35
+ let active = -1;
36
+ let renderedQuery: string | undefined;
37
+
38
+ function cancel() {
39
+ revision += 1;
40
+ clearTimeout(timer);
41
+ timer = undefined;
42
+ request?.abort();
43
+ request = undefined;
44
+ list!.removeAttribute('aria-busy');
45
+ }
46
+ function select(index: number) {
47
+ active = index;
48
+ links.forEach((link, position) => link.setAttribute('aria-selected', String(position === active)));
49
+ if (links[active]) input!.setAttribute('aria-activedescendant', links[active].id);
50
+ else input!.removeAttribute('aria-activedescendant');
51
+ }
52
+ function close() {
53
+ cancel();
54
+ panel!.hidden = true;
55
+ input!.setAttribute('aria-expanded', 'false');
56
+ select(-1);
57
+ }
58
+ function message(text: string) {
59
+ links = [];
60
+ select(-1);
61
+ list!.replaceChildren();
62
+ list!.hidden = true;
63
+ status!.textContent = text;
64
+ }
65
+ function show() {
66
+ panel!.hidden = false;
67
+ input!.setAttribute('aria-expanded', 'true');
68
+ }
69
+ function render(results: SearchResult[]) {
70
+ message(results.length ? '' : 'No results');
71
+ const fragment = document.createDocumentFragment();
72
+ links = results.map((result, index) => {
73
+ const item = document.createElement('li');
74
+ item.setAttribute('role', 'none');
75
+ const link = document.createElement('a');
76
+ link.id = `${list!.id}-${index}`;
77
+ link.href = result.href;
78
+ link.tabIndex = -1;
79
+ link.setAttribute('role', 'option');
80
+ link.setAttribute('aria-selected', 'false');
81
+ const title = document.createElement('span');
82
+ title.className = 'docs-search-result-title';
83
+ title.textContent = result.titlePath.join(' > ');
84
+ const snippet = document.createElement('span');
85
+ snippet.className = 'docs-search-result-snippet';
86
+ snippet.textContent = result.snippet;
87
+ link.appendChild(title);
88
+ link.appendChild(snippet);
89
+ item.appendChild(link);
90
+ fragment.appendChild(item);
91
+ return link;
92
+ });
93
+ list!.appendChild(fragment);
94
+ list!.hidden = !links.length;
95
+ }
96
+ function search() {
97
+ cancel();
98
+ show();
99
+ renderedQuery = undefined;
100
+ const query = input!.value.trim();
101
+ if (query.length < 2) { message('Search the docs'); return; }
102
+ message('Searching…');
103
+ const current = revision;
104
+ timer = setTimeout(async () => {
105
+ const controller = new AbortController();
106
+ request = controller;
107
+ list!.setAttribute('aria-busy', 'true');
108
+ try {
109
+ const endpoint = new URL(baseEndpoint);
110
+ endpoint.searchParams.set('q', query);
111
+ const response = await fetch(endpoint, { signal: controller.signal, headers: { Accept: 'application/json' } });
112
+ if (!response.ok) throw new Error('Search request failed');
113
+ const results = readResults(await response.json());
114
+ if (current !== revision || controller.signal.aborted) return;
115
+ renderedQuery = query;
116
+ render(results);
117
+ } catch {
118
+ if (current === revision && !controller.signal.aborted) message('Search unavailable');
119
+ } finally {
120
+ if (current === revision) {
121
+ request = undefined;
122
+ list!.removeAttribute('aria-busy');
123
+ }
124
+ }
125
+ }, 240);
126
+ }
127
+ const options = { signal: listeners.signal };
128
+ input.addEventListener('input', search, options);
129
+ input.addEventListener('focus', () => {
130
+ if (renderedQuery === input.value.trim()) show();
131
+ else search();
132
+ }, options);
133
+ input.addEventListener('keydown', event => {
134
+ if (event.isComposing) return;
135
+ if (event.key === 'Escape') { event.preventDefault(); close(); }
136
+ else if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
137
+ event.preventDefault();
138
+ if (panel.hidden && renderedQuery !== input.value.trim()) search();
139
+ else show();
140
+ if (links.length) {
141
+ const next = active < 0 ? (event.key === 'ArrowDown' ? 0 : links.length - 1)
142
+ : (active + (event.key === 'ArrowDown' ? 1 : -1) + links.length) % links.length;
143
+ select(next);
144
+ links[next].scrollIntoView({ block: 'nearest' });
145
+ }
146
+ } else if (event.key === 'Enter' && !panel.hidden && links.length) {
147
+ event.preventDefault();
148
+ links[active < 0 ? 0 : active].click();
149
+ }
150
+ }, options);
151
+ list.addEventListener('pointerdown', event => event.preventDefault(), options);
152
+ list.addEventListener('pointerover', event => {
153
+ const target = event.target instanceof Element ? event.target.closest('a') : null;
154
+ const index = links.findIndex(link => link === target);
155
+ if (index >= 0) select(index);
156
+ }, options);
157
+ document.addEventListener('pointerdown', event => {
158
+ if (event.target instanceof Node && !root.contains(event.target)) close();
159
+ }, options);
160
+ document.addEventListener('focusin', event => {
161
+ if (event.target instanceof Node && !root.contains(event.target)) close();
162
+ }, options);
163
+ document.addEventListener('keydown', event => {
164
+ if (event.key !== '/' || event.defaultPrevented || event.isComposing || event.ctrlKey || event.metaKey || event.altKey) return;
165
+ const target = event.target;
166
+ if (target instanceof Element && target.closest('input, textarea, select, [contenteditable]:not([contenteditable="false"])')) return;
167
+ const details = root.closest('details');
168
+ if (!input.getClientRects().length && !(details && !details.open && details.getClientRects().length)) return;
169
+ event.preventDefault();
170
+ if (details) details.open = true;
171
+ input.focus();
172
+ input.select();
173
+ }, options);
174
+ return () => { close(); listeners.abort(); mounted.delete(root); };
175
+ }
176
+
177
+ /** Idempotent enhancement; cleanup only removes instances created by this call. */
178
+ export function initDocsSearch(scope: ParentNode = document): () => void {
179
+ const roots = Array.from(scope.querySelectorAll<HTMLElement>('[data-docs-search]'));
180
+ if (scope instanceof HTMLElement && scope.matches('[data-docs-search]')) roots.unshift(scope);
181
+ const cleanups: (() => void)[] = [];
182
+ for (const root of roots) {
183
+ if (mounted.has(root)) continue;
184
+ const cleanup = mount(root);
185
+ mounted.set(root, cleanup);
186
+ cleanups.push(cleanup);
187
+ }
188
+ return () => cleanups.forEach(cleanup => cleanup());
189
+ }
190
+
191
+ if (typeof document !== 'undefined') {
192
+ if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', () => initDocsSearch(), { once: true });
193
+ else initDocsSearch();
194
+ }
@@ -0,0 +1,63 @@
1
+ import { createHash } from 'node:crypto';
2
+
3
+ export const model = '@cf/baai/bge-base-en-v1.5';
4
+ export const pooling = 'cls';
5
+ export const dimensions = 768;
6
+ const digest = value => createHash('sha256').update(value).digest('hex');
7
+
8
+ // Keep long sections inside the model's context. Every part keeps the same
9
+ // heading link; retrieval collapses duplicate links after scoring.
10
+ function parts(text) {
11
+ const chunks = [];
12
+ // Paragraph boundaries are stable cache boundaries. Within a long paragraph,
13
+ // keep sentences together so a short task isn't diluted by an entire guide.
14
+ for (const paragraph of text.split(/\n\n+/).filter(Boolean)) {
15
+ let part = '';
16
+ const sentences = paragraph.split(/(?<=[.!?])\s+/);
17
+ for (const sentence of sentences) {
18
+ if (part && part.length + sentence.length > 650) { chunks.push(part.trim()); part = ''; }
19
+ if (sentence.length > 650) {
20
+ for (const word of sentence.split(/\s+/).filter(Boolean)) {
21
+ if (part && part.length + word.length > 650) { chunks.push(part.trim()); part = ''; }
22
+ if (word.length > 650) {
23
+ if (part) { chunks.push(part.trim()); part = ''; }
24
+ for (let i = 0; i < word.length; i += 650) chunks.push(word.slice(i, i + 650));
25
+ } else part += `${part ? ' ' : ''}${word}`;
26
+ }
27
+ } else part += `${part ? ' ' : ''}${sentence.trim()}`;
28
+ }
29
+ if (part.trim()) chunks.push(part.trim());
30
+ }
31
+ return chunks;
32
+ }
33
+
34
+ export function searchChunks(pages) {
35
+ return pages.flatMap(page => page.searchSections.flatMap(section => parts(section.text).map(text => {
36
+ const href = `${page.href}#${section.anchor}`;
37
+ const hash = digest(JSON.stringify([model, pooling, href, section.titlePath, text]));
38
+ return { ...section, text, href, hash };
39
+ })));
40
+ }
41
+
42
+ export function validVector(vector) {
43
+ return Array.isArray(vector) && vector.length === dimensions && vector.every(Number.isFinite) && vector.some(value => value !== 0);
44
+ }
45
+
46
+ export async function buildSearchIndex(pages, { previous = [], embed, onBatch = () => {} }) {
47
+ const chunks = searchChunks(pages);
48
+ const cached = new Map(previous.filter(index => index?.version === 1 && index.model === model && index.pooling === pooling && index.dimensions === dimensions)
49
+ .flatMap(index => index.chunks).filter(chunk => validVector(chunk.vector)).map(chunk => [chunk.hash, chunk.vector]));
50
+ const missing = chunks.filter(chunk => !cached.has(chunk.hash));
51
+ let embedded = 0;
52
+ for (let offset = 0; offset < missing.length; offset += 32) {
53
+ const batch = missing.slice(offset, offset + 32);
54
+ const response = await embed(model, { text: batch.map(chunk => `${chunk.titlePath.join(' > ')}\n${chunk.text}`), pooling });
55
+ if (response.data?.length !== batch.length || !response.data.every(validVector)) throw Error('Workers AI returned invalid embeddings; search build stopped.');
56
+ batch.forEach((chunk, i) => cached.set(chunk.hash, response.data[i].map(value => Number(value.toFixed(6)))));
57
+ embedded += batch.length;
58
+ onBatch({ embedded, total: missing.length });
59
+ }
60
+ const index = { version: 1, model, pooling, dimensions, corpusHash: digest(chunks.map(chunk => chunk.hash).join('\n')),
61
+ chunks: chunks.map(chunk => ({ ...chunk, vector: cached.get(chunk.hash) })) };
62
+ return { index, counts: { total: chunks.length, reused: chunks.length - embedded, embedded } };
63
+ }
@@ -0,0 +1,16 @@
1
+ import type { SearchIndex, SearchResult } from './types';
2
+
3
+ const magnitude = (vector: number[]) => Math.sqrt(vector.reduce((sum, value) => sum + value * value, 0));
4
+ export function search(index: SearchIndex, query: number[], minimumScore = 0.55): SearchResult[] {
5
+ if (query.length !== index.dimensions || !query.every(Number.isFinite)) throw Error('Invalid query embedding');
6
+ const norm = magnitude(query);
7
+ if (!norm) throw Error('Empty query embedding');
8
+ const ranked = index.chunks.map(chunk => ({
9
+ href: chunk.href,
10
+ titlePath: chunk.titlePath,
11
+ snippet: chunk.text.length > 155 ? `${chunk.text.slice(0, 154).replace(/\s+\S*$/, '')}…` : chunk.text,
12
+ score: chunk.vector.reduce((sum, value, i) => sum + value * query[i], 0) / (norm * magnitude(chunk.vector)),
13
+ })).filter(result => result.score >= minimumScore).sort((a, b) => b.score - a.score);
14
+ const seen = new Set<string>();
15
+ return ranked.filter(result => { if (seen.has(result.href)) return false; seen.add(result.href); return true; }).slice(0, 5);
16
+ }
@@ -0,0 +1,19 @@
1
+ /* Inline results stay inside the sidebar's scroll area and the phone menu. */
2
+ .docs-search { min-width: 0; margin-bottom: 26px; color: var(--ink); }
3
+ .docs-search-label { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; border: 0; }
4
+ .docs-search-field { display: flex; align-items: center; gap: 8px; min-width: 0; min-height: 44px; padding: 0 10px; border: 1px solid var(--rule); border-radius: 7px; background: var(--paper); }
5
+ .docs-search-field:focus-within { outline: 2px solid var(--ink); outline-offset: 2px; }
6
+ .docs-search input { display: block; width: 100%; min-width: 0; min-height: 42px; padding: 8px 0; border: 0; border-radius: 0; outline: none; background: transparent; color: var(--ink); font: inherit; font-size: 15px; line-height: 1.4; }
7
+ .docs-search input::-webkit-search-cancel-button { filter: grayscale(1); }
8
+ .docs-search input::placeholder { color: var(--ink-soft); opacity: 1; }
9
+ .docs-search kbd { flex: none; padding: 0 5px; border: 1px solid var(--rule); border-radius: 3px; color: var(--ink-soft); font: inherit; font-size: 12px; line-height: 20px; }
10
+ .docs-search-panel { margin-top: 10px; }
11
+ .docs-search-status { margin: 0; color: var(--ink-soft); font-size: 14px; line-height: 1.4; }
12
+ .docs-search-status:empty { display: none; }
13
+ .docs-search-results { display: grid; margin: 0; padding: 0; list-style: none; }
14
+ .docs-search-results li { min-width: 0; border-bottom: 1px solid var(--rule); }
15
+ .docs-search-results a { display: block; min-width: 0; padding: 10px 5px; border-radius: 3px; color: var(--ink); text-decoration: none; }
16
+ .docs-search-results a:is(:hover, [aria-selected="true"]) { outline: 1px solid var(--ink); outline-offset: -1px; }
17
+ .docs-search-result-title { display: block; font-size: 14px; font-weight: 500; line-height: 1.4; overflow-wrap: anywhere; }
18
+ .docs-search-result-snippet { display: block; overflow: hidden; margin-top: 3px; color: var(--ink-soft); font-size: 13px; line-height: 1.4; text-overflow: ellipsis; white-space: nowrap; }
19
+ .docs-search [hidden] { display: none; }