@foggy-projects/deepseek-harness-plugin 0.4.2-rc.5 → 0.4.5-rc.1

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 (53) hide show
  1. package/README.md +224 -185
  2. package/THIRD-PARTY-RUNTIME-NOTICES.md +16 -16
  3. package/cordis.patch.yml +6 -6
  4. package/docs/COMMUNITY-MARKETPLACES.md +64 -64
  5. package/docs/PUBLIC-BETA-READINESS.md +109 -109
  6. package/docs/RELEASE-CANDIDATE-0.4.0-RC.2.md +38 -38
  7. package/docs/RELEASE-CANDIDATE-0.4.0-RC.3.md +18 -18
  8. package/docs/RELEASE-CANDIDATE-0.4.1-DSH-0.1.5-RC.1.md +60 -60
  9. package/docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.1.md +62 -62
  10. package/docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.2.md +50 -50
  11. package/docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.3.md +34 -34
  12. package/docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.4.md +32 -32
  13. package/docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.5.md +27 -27
  14. package/docs/RELEASE-CANDIDATE-0.4.3-DSH-0.2.0-RC.1.md +96 -0
  15. package/docs/RELEASE-CANDIDATE-0.4.4-DSH-0.2.1-RC.1.md +135 -0
  16. package/docs/RELEASE-CANDIDATE-0.4.5-DSH-0.2.2-RC.1.md +45 -0
  17. package/docs/WINDOWS-BETA-ACCEPTANCE.md +113 -113
  18. package/experience/linux/README.md +53 -53
  19. package/experience/linux/prepare.sh +4 -4
  20. package/lib/atomic-json.js +41 -41
  21. package/lib/client.js +1222 -1031
  22. package/lib/component-manager.js +164 -0
  23. package/lib/component-releases.js +363 -0
  24. package/lib/diagnostics.js +86 -86
  25. package/lib/index.js +764 -698
  26. package/lib/operation-lock.js +139 -0
  27. package/lib/python-runtime.js +339 -339
  28. package/lib/query-tool.js +134 -131
  29. package/lib/remote-descriptor.js +74 -59
  30. package/lib/remote.js +8 -8
  31. package/lib/runtime-settings.js +89 -89
  32. package/lib/skill-provider.js +116 -116
  33. package/lib/typert.js +9 -9
  34. package/lib/version.js +20 -20
  35. package/lib/viewer-preview.js +50 -27
  36. package/package.json +20 -16
  37. package/skills/foggy-deepseek-onboarding/SKILL.md +149 -143
  38. package/skills/foggy-deepseek-onboarding/assets/connection.schema.json +48 -48
  39. package/skills/foggy-deepseek-onboarding/assets/datasource.example.json +14 -14
  40. package/skills/foggy-deepseek-onboarding/assets/env.example +14 -14
  41. package/skills/foggy-deepseek-onboarding/assets/onboarding-state.schema.json +71 -71
  42. package/skills/foggy-deepseek-onboarding/assets/semantic-plan.example.json +8 -8
  43. package/skills/foggy-deepseek-onboarding/assets/semantic-plan.schema.json +21 -21
  44. package/skills/foggy-deepseek-onboarding/assets/versions.json +24 -24
  45. package/skills/foggy-deepseek-onboarding/references/onboarding-workflow.md +168 -168
  46. package/skills/foggy-deepseek-onboarding/scripts/doctor.ps1 +4 -4
  47. package/skills/foggy-deepseek-onboarding/scripts/install.ps1 +4 -4
  48. package/skills/foggy-deepseek-onboarding/scripts/invoke-onboarding.ps1 +32 -32
  49. package/skills/foggy-deepseek-onboarding/scripts/onboard.ps1 +4 -4
  50. package/skills/foggy-deepseek-onboarding/scripts/onboarding.py +3721 -3697
  51. package/skills/foggy-deepseek-onboarding/scripts/runtime-start.ps1 +4 -4
  52. package/skills/foggy-deepseek-onboarding/scripts/runtime-stop.ps1 +4 -4
  53. package/skills/foggy-deepseek-onboarding/scripts/uninstall.ps1 +4 -4
@@ -0,0 +1,164 @@
1
+ import { access, readFile, readdir } from 'node:fs/promises'
2
+ import { join, relative, isAbsolute } from 'node:path'
3
+ import { writeJsonAtomic } from './atomic-json.js'
4
+ import { checkComponentReleases, compareReleaseVersions, resolveComponentRelease, validateComponentRelease } from './component-releases.js'
5
+
6
+ const KINDS = ['launcher', 'cli']
7
+ const HISTORY_SCHEMA = 'foggy-component-history/v1'
8
+ const MINIMUM_VERSION = '0.1.24'
9
+
10
+ async function readJson(path) {
11
+ try { return JSON.parse(await readFile(path, 'utf8')) } catch { return null }
12
+ }
13
+
14
+ function assertSupported(kind, version) {
15
+ if (!KINDS.includes(kind)) throw new Error('Select Launcher or CLI.')
16
+ if (compareReleaseVersions(version, MINIMUM_VERSION) < 0) throw new Error(`This plugin requires ${kind === 'cli' ? 'CLI' : 'Launcher'} ${MINIMUM_VERSION} or later.`)
17
+ }
18
+
19
+ export function effectiveComponentVersions(bundled, state) {
20
+ const manifest = structuredClone(bundled)
21
+ manifest.componentSelections = {}
22
+ for (const kind of KINDS) {
23
+ const selection = state?.componentSelections?.[kind]
24
+ if (!selection) continue
25
+ const component = validateComponentRelease(kind, selection)
26
+ assertSupported(kind, component.version)
27
+ manifest.components[kind] = component
28
+ manifest.componentSelections[kind] = component
29
+ }
30
+ return manifest
31
+ }
32
+
33
+ function assetList(kind, component) {
34
+ return kind === 'launcher' ? component.assets : [component.wheel, component.checksums]
35
+ }
36
+
37
+ function componentFromState(kind, state) {
38
+ if (!state?.[kind]?.version) return null
39
+ if (state.componentManifests?.[kind]) return validateComponentRelease(kind, state.componentManifests[kind])
40
+ // Older plugin releases saved hashes and paths, but not complete component manifests.
41
+ const { version } = state[kind]
42
+ const tag = kind === 'launcher' ? `foggy-runtime-launcher-v${version}` : `v${version}`
43
+ const repository = kind === 'launcher' ? 'foggy-data-mcp-bridge' : 'foggy-runtime-cli'
44
+ const names = kind === 'launcher'
45
+ ? [`foggy-runtime-launcher-${version}.jar`, 'start-foggy-runtime.ps1', 'start-foggy-runtime.sh', 'README-foggy-runtime-launcher.md', 'runtime-launcher-manifest.json', 'SHA256SUMS']
46
+ : [`foggy_runtime_cli-${version}-py3-none-any.whl`, 'SHA256SUMS']
47
+ const assets = names.map((file) => {
48
+ const candidates = (state.verifiedAssets || []).filter((asset) => asset.file === file && asset.path
49
+ && (kind === 'launcher' ? relative(state.launcher.path, asset.path) === file : relative(join(state.installRoot, 'downloads', 'cli'), asset.path) === file))
50
+ if (candidates.length !== 1) throw new Error('The previous component does not have a complete verified asset receipt.')
51
+ return { file, sha256: candidates[0].sha256, url: `https://github.com/foggy-projects/${repository}/releases/download/${tag}/${file}` }
52
+ })
53
+ return validateComponentRelease(kind, kind === 'launcher'
54
+ ? { version, minimumJavaVersion: '17.0.0', runtimeApiContract: 'foggy-runtime-api/v1', assets }
55
+ : { version, minimumPythonVersion: '3.11.0', wheel: assets[0], checksums: assets[1] })
56
+ }
57
+
58
+ function within(root, path) {
59
+ const suffix = relative(root, path)
60
+ return suffix !== '' && suffix !== '..' && !suffix.startsWith(`..\\`) && !suffix.startsWith('../') && !isAbsolute(suffix)
61
+ }
62
+
63
+ export async function rememberInstalledComponents(roots, state) {
64
+ const warnings = []
65
+ if (!state) return warnings
66
+ for (const kind of KINDS) {
67
+ let component
68
+ try { component = componentFromState(kind, state) } catch { continue }
69
+ if (!component) continue
70
+ const assets = assetList(kind, component).map((asset) => {
71
+ const verified = state.verifiedAssets?.find((entry) => entry.file === asset.file && entry.sha256 === asset.sha256
72
+ && typeof entry.path === 'string' && within(roots.installRoot, entry.path))
73
+ return verified ? { file: asset.file, sha256: asset.sha256, path: verified.path } : null
74
+ })
75
+ if (assets.some((asset) => !asset)) continue
76
+ try {
77
+ await writeJsonAtomic(join(roots.installRoot, 'component-history', kind, `${component.version}.json`), {
78
+ schemaVersion: HISTORY_SCHEMA, component, assets, installedAt: state.installedAt || null,
79
+ })
80
+ } catch { warnings.push(`Could not save ${kind === 'cli' ? 'CLI' : 'Launcher'} download history. Check the component directory permissions and free space.`) }
81
+ }
82
+ return warnings
83
+ }
84
+
85
+ async function downloadedComponents(roots) {
86
+ const result = { launcher: new Map(), cli: new Map() }
87
+ for (const kind of KINDS) {
88
+ const directory = join(roots.installRoot, 'component-history', kind)
89
+ let files
90
+ try { files = await readdir(directory) } catch { continue }
91
+ for (const name of files.slice(0, 200)) {
92
+ if (!name.endsWith('.json')) continue
93
+ try {
94
+ const receipt = await readJson(join(directory, name))
95
+ if (receipt?.schemaVersion !== HISTORY_SCHEMA) continue
96
+ const component = validateComponentRelease(kind, receipt.component)
97
+ assertSupported(kind, component.version)
98
+ const expected = assetList(kind, component)
99
+ if (!Array.isArray(receipt.assets) || receipt.assets.length !== expected.length) continue
100
+ for (const asset of expected) {
101
+ const entry = receipt.assets.find((item) => item.file === asset.file && item.sha256 === asset.sha256)
102
+ if (!entry || typeof entry.path !== 'string' || !within(roots.installRoot, entry.path)) throw new Error('Invalid saved component path.')
103
+ await access(entry.path)
104
+ }
105
+ result[kind].set(component.version, component)
106
+ } catch { /* Incomplete or invalid downloads must not be offered for offline use. */ }
107
+ }
108
+ }
109
+ return result
110
+ }
111
+
112
+ export async function componentVersions({ roots, bundled, state, force = false, ...options }) {
113
+ const warnings = await rememberInstalledComponents(roots, state)
114
+ const [catalog, local] = await Promise.all([
115
+ checkComponentReleases({ dataRoot: roots.dataRoot, force, ...options }),
116
+ downloadedComponents(roots),
117
+ ])
118
+ const effective = effectiveComponentVersions(bundled, state)
119
+ const components = {}
120
+ for (const kind of KINDS) {
121
+ const source = catalog.components[kind]
122
+ const releases = new Map(source.releases.map((release) => [release.version, { ...release, downloaded: local[kind].has(release.version) }]))
123
+ for (const version of [bundled.components[kind].version, ...local[kind].keys()]) {
124
+ if (!releases.has(version)) releases.set(version, {
125
+ version, prerelease: kind === 'launcher', publishedAt: null,
126
+ url: `https://github.com/foggy-projects/${kind === 'launcher' ? 'foggy-data-mcp-bridge' : 'foggy-runtime-cli'}/releases/tag/${kind === 'launcher' ? 'foggy-runtime-launcher-v' : 'v'}${version}`,
127
+ installable: true, downloaded: local[kind].has(version),
128
+ })
129
+ }
130
+ const entries = [...releases.values()].map((release) => {
131
+ try { assertSupported(kind, release.version); return release } catch (error) { return { ...release, installable: false, unavailableReason: error.message } }
132
+ }).sort((a, b) => compareReleaseVersions(b.version, a.version))
133
+ components[kind] = {
134
+ ...source, releases: entries,
135
+ installedVersion: state?.[kind]?.version || null,
136
+ selectedVersion: effective.components[kind].version,
137
+ bundledVersion: bundled.components[kind].version,
138
+ }
139
+ }
140
+ return { checkedAt: catalog.checkedAt, stale: catalog.stale, error: catalog.error, components, warnings }
141
+ }
142
+
143
+ export async function prepareComponentVersion({ roots, bundled, state, component: kind, version, ...options }) {
144
+ assertSupported(kind, version)
145
+ const warnings = await rememberInstalledComponents(roots, state)
146
+ if (warnings.length) throw new Error(warnings.join(' '))
147
+ const local = await downloadedComponents(roots)
148
+ const component = local[kind].get(version)
149
+ || (bundled.components[kind].version === version ? validateComponentRelease(kind, bundled.components[kind]) : await resolveComponentRelease(kind, version, { dataRoot: roots.dataRoot, ...options }))
150
+ const manifest = effectiveComponentVersions(bundled, state)
151
+ // A Launcher selection must not silently change CLI, or vice versa.
152
+ for (const other of KINDS.filter((item) => item !== kind)) {
153
+ const installed = componentFromState(other, state)
154
+ if (!installed) throw new Error(`Repair ${other === 'cli' ? 'CLI' : 'Launcher'} before selecting component versions.`)
155
+ if (compareReleaseVersions(installed.version, MINIMUM_VERSION) < 0) {
156
+ throw new Error('Use Update components first to upgrade this older installation before selecting individual component versions.')
157
+ }
158
+ manifest.components[other] = installed
159
+ manifest.componentSelections[other] = installed
160
+ }
161
+ manifest.components[kind] = component
162
+ manifest.componentSelections[kind] = component
163
+ return manifest
164
+ }
@@ -0,0 +1,363 @@
1
+ import { createHash } from 'node:crypto'
2
+ import { readFile } from 'node:fs/promises'
3
+ import { join } from 'node:path'
4
+ import { writeJsonAtomic } from './atomic-json.js'
5
+
6
+ const CACHE_SCHEMA = 'foggy-component-releases/v1'
7
+ const CACHE_TTL = 6 * 60 * 60_000
8
+ const FAILURE_TTL = 15 * 60_000
9
+ const PAGE_SIZE = 30
10
+ const MAX_PAGES = 3
11
+ const MAX_RELEASES = 30
12
+ const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?$/
13
+ const SHA256 = /^[a-f0-9]{64}$/
14
+ const SOURCES = {
15
+ launcher: { repository: 'foggy-projects/foggy-data-mcp-bridge', prefix: 'foggy-runtime-launcher-v' },
16
+ cli: { repository: 'foggy-projects/foggy-runtime-cli', prefix: 'v' },
17
+ }
18
+ const checks = new Map()
19
+
20
+ export class ComponentReleaseError extends Error {
21
+ constructor(code, message) {
22
+ super(message)
23
+ this.name = 'ComponentReleaseError'
24
+ this.code = code
25
+ }
26
+ }
27
+
28
+ function fail(code, message) {
29
+ throw new ComponentReleaseError(code, message)
30
+ }
31
+
32
+ function sourceFor(kind) {
33
+ const source = SOURCES[kind]
34
+ if (!source) fail('COMPONENT_KIND_INVALID', 'Select Launcher or CLI.')
35
+ return source
36
+ }
37
+
38
+ function validVersion(version) {
39
+ if (typeof version !== 'string' || version.length > 80) return false
40
+ const match = version.match(VERSION)
41
+ return Boolean(match && (!match[4] || match[4].split('.').every((part) => /^[0-9A-Za-z-]+$/.test(part) && !/^0\d+$/.test(part))))
42
+ }
43
+
44
+ function compareNumeric(left, right) {
45
+ if (left.length !== right.length) return Math.sign(left.length - right.length)
46
+ return left === right ? 0 : left < right ? -1 : 1
47
+ }
48
+
49
+ export function compareReleaseVersions(left, right) {
50
+ if (!validVersion(left) || !validVersion(right)) fail('COMPONENT_VERSION_INVALID', 'Invalid component version.')
51
+ const a = String(left).match(VERSION)
52
+ const b = String(right).match(VERSION)
53
+ for (let index = 1; index <= 3; index += 1) {
54
+ const result = compareNumeric(a[index], b[index])
55
+ if (result) return result
56
+ }
57
+ if (!a[4] && !b[4]) return 0
58
+ if (!a[4]) return 1
59
+ if (!b[4]) return -1
60
+ const aParts = a[4].split('.')
61
+ const bParts = b[4].split('.')
62
+ for (let index = 0; index < Math.max(aParts.length, bParts.length); index += 1) {
63
+ if (aParts[index] === bParts[index]) continue
64
+ if (aParts[index] === undefined) return -1
65
+ if (bParts[index] === undefined) return 1
66
+ const aNumeric = /^\d+$/.test(aParts[index])
67
+ const bNumeric = /^\d+$/.test(bParts[index])
68
+ if (aNumeric && bNumeric) return compareNumeric(aParts[index], bParts[index])
69
+ if (aNumeric !== bNumeric) return aNumeric ? -1 : 1
70
+ return aParts[index] < bParts[index] ? -1 : 1
71
+ }
72
+ return 0
73
+ }
74
+
75
+ function requiredFiles(kind, version) {
76
+ return kind === 'launcher'
77
+ ? [
78
+ `foggy-runtime-launcher-${version}.jar`,
79
+ 'start-foggy-runtime.ps1',
80
+ 'start-foggy-runtime.sh',
81
+ 'README-foggy-runtime-launcher.md',
82
+ 'runtime-launcher-manifest.json',
83
+ 'SHA256SUMS',
84
+ ]
85
+ : [`foggy_runtime_cli-${version}-py3-none-any.whl`, 'SHA256SUMS']
86
+ }
87
+
88
+ function releaseUrl(kind, tag) {
89
+ return `https://github.com/${sourceFor(kind).repository}/releases/tag/${tag}`
90
+ }
91
+
92
+ function assetUrl(kind, tag, file) {
93
+ return `https://github.com/${sourceFor(kind).repository}/releases/download/${tag}/${file}`
94
+ }
95
+
96
+ function verifiedAsset(kind, tag, file, assets) {
97
+ const matching = assets.filter((asset) => asset?.name === file)
98
+ if (matching.length !== 1) fail('COMPONENT_ASSET_MISSING', `Release requires exactly one ${file} asset.`)
99
+ const asset = matching[0]
100
+ if (asset.browser_download_url !== assetUrl(kind, tag, file)) {
101
+ fail('COMPONENT_ASSET_UNTRUSTED', `Release asset ${file} does not use the official download URL.`)
102
+ }
103
+ if (asset.digest != null && !/^sha256:[a-f0-9]{64}$/.test(asset.digest)) {
104
+ fail('COMPONENT_DIGEST_INVALID', `Release asset ${file} has an invalid SHA256 digest.`)
105
+ }
106
+ return asset
107
+ }
108
+
109
+ function normalizeRelease(kind, release) {
110
+ const source = sourceFor(kind)
111
+ if (!release || release.draft || typeof release.tag_name !== 'string' || !release.tag_name.startsWith(source.prefix)) return null
112
+ const version = release.tag_name.slice(source.prefix.length)
113
+ if (!validVersion(version)) return null
114
+ const tag = `${source.prefix}${version}`
115
+ if (release.tag_name !== tag || release.html_url !== releaseUrl(kind, tag)) return null
116
+ let unavailableReason = null
117
+ try {
118
+ if (!Array.isArray(release.assets)) fail('COMPONENT_ASSET_MISSING', 'Release assets are unavailable.')
119
+ for (const file of requiredFiles(kind, version)) verifiedAsset(kind, tag, file, release.assets)
120
+ } catch (error) {
121
+ unavailableReason = error.message
122
+ }
123
+ return {
124
+ version,
125
+ tag,
126
+ prerelease: Boolean(release.prerelease || version.includes('-')),
127
+ publishedAt: typeof release.published_at === 'string' && Number.isFinite(Date.parse(release.published_at)) ? release.published_at : null,
128
+ url: releaseUrl(kind, tag),
129
+ installable: unavailableReason === null,
130
+ ...(unavailableReason ? { unavailableReason } : {}),
131
+ }
132
+ }
133
+
134
+ function emptyComponent() {
135
+ return { latestVersion: null, latestStableVersion: null, checkedAt: null, releases: [] }
136
+ }
137
+
138
+ function emptyCatalog() {
139
+ return { checkedAt: null, attemptedAt: null, stale: true, error: null, components: { launcher: emptyComponent(), cli: emptyComponent() } }
140
+ }
141
+
142
+ function validateCachedComponent(kind, component) {
143
+ if (!component || !Array.isArray(component.releases) || component.releases.length > MAX_RELEASES) return emptyComponent()
144
+ const releases = component.releases.filter((release) => validVersion(release?.version)
145
+ && release.tag === `${sourceFor(kind).prefix}${release.version}`
146
+ && release.url === releaseUrl(kind, release.tag)
147
+ && typeof release.installable === 'boolean')
148
+ .map(({ version, tag, prerelease, publishedAt, url, installable, unavailableReason }) => ({ version, tag, prerelease: Boolean(prerelease || version.includes('-')), publishedAt: typeof publishedAt === 'string' && Number.isFinite(Date.parse(publishedAt)) ? publishedAt : null, url, installable, ...(unavailableReason ? { unavailableReason: String(unavailableReason).slice(0, 300) } : {}) }))
149
+ .sort((a, b) => compareReleaseVersions(b.version, a.version))
150
+ return {
151
+ latestVersion: releases[0]?.version ?? null,
152
+ latestStableVersion: releases.find((release) => !release.prerelease)?.version ?? null,
153
+ checkedAt: Number.isFinite(Date.parse(component.checkedAt)) ? component.checkedAt : null,
154
+ releases,
155
+ }
156
+ }
157
+
158
+ export function componentReleaseCachePath(dataRoot) {
159
+ return join(dataRoot, 'component-releases.json')
160
+ }
161
+
162
+ export async function readComponentReleaseCache(dataRoot, { now = Date.now } = {}) {
163
+ try {
164
+ const payload = JSON.parse(await readFile(componentReleaseCachePath(dataRoot), 'utf8'))
165
+ if (payload.schemaVersion !== CACHE_SCHEMA) return emptyCatalog()
166
+ const checkedAt = Number.isFinite(Date.parse(payload.checkedAt)) ? payload.checkedAt : null
167
+ return {
168
+ checkedAt,
169
+ attemptedAt: Number.isFinite(Date.parse(payload.attemptedAt)) ? payload.attemptedAt : null,
170
+ stale: Boolean(payload.stale || !checkedAt || now() - Date.parse(checkedAt) >= CACHE_TTL),
171
+ error: typeof payload.error === 'string' ? payload.error.slice(0, 600) : null,
172
+ components: {
173
+ launcher: validateCachedComponent('launcher', payload.components?.launcher),
174
+ cli: validateCachedComponent('cli', payload.components?.cli),
175
+ },
176
+ }
177
+ } catch {
178
+ return emptyCatalog()
179
+ }
180
+ }
181
+
182
+ async function requestText(url, { fetchImpl = globalThis.fetch, timeoutMs = 10_000, api = false, maxBytes = 3 * 1024 * 1024 } = {}) {
183
+ let response
184
+ try {
185
+ response = await fetchImpl(url, {
186
+ signal: AbortSignal.timeout(timeoutMs),
187
+ redirect: api ? 'error' : 'follow',
188
+ headers: { Accept: api ? 'application/vnd.github+json' : 'application/octet-stream', 'User-Agent': 'Foggy-DeepSeek-Harness-Plugin', ...(api ? { 'X-GitHub-Api-Version': '2022-11-28' } : {}) },
189
+ })
190
+ } catch {
191
+ fail('COMPONENT_RELEASE_NETWORK', 'Cannot reach the official component release service; check your network and try again.')
192
+ }
193
+ if (!response.ok) {
194
+ fail('COMPONENT_RELEASE_HTTP', response.status === 403 || response.status === 429
195
+ ? 'GitHub release checks are temporarily rate limited; try again later.'
196
+ : `Official component release request failed (HTTP ${response.status}).`)
197
+ }
198
+ const length = Number(response.headers?.get?.('content-length'))
199
+ if (length > maxBytes) fail('COMPONENT_RELEASE_TOO_LARGE', 'Official release metadata exceeds the supported size.')
200
+ const bytes = new Uint8Array(await response.arrayBuffer())
201
+ if (bytes.byteLength > maxBytes) fail('COMPONENT_RELEASE_TOO_LARGE', 'Official release metadata exceeds the supported size.')
202
+ return { text: new TextDecoder('utf-8', { fatal: true }).decode(bytes), bytes }
203
+ }
204
+
205
+ async function requestJson(url, options) {
206
+ const { text } = await requestText(url, { ...options, api: true })
207
+ try { return JSON.parse(text) } catch { fail('COMPONENT_RELEASE_INVALID', 'The official release service returned invalid metadata.') }
208
+ }
209
+
210
+ async function discoverComponent(kind, options) {
211
+ const source = sourceFor(kind)
212
+ const releases = []
213
+ for (let page = 1; page <= MAX_PAGES; page += 1) {
214
+ const payload = await requestJson(`https://api.github.com/repos/${source.repository}/releases?per_page=${PAGE_SIZE}&page=${page}`, options)
215
+ if (!Array.isArray(payload)) fail('COMPONENT_RELEASE_INVALID', 'The official release service did not return a release list.')
216
+ for (const release of payload) {
217
+ const normalized = normalizeRelease(kind, release)
218
+ if (normalized && !releases.some((item) => item.version === normalized.version)) releases.push(normalized)
219
+ }
220
+ if (payload.length < PAGE_SIZE) break
221
+ }
222
+ releases.sort((a, b) => compareReleaseVersions(b.version, a.version))
223
+ const visible = releases.slice(0, MAX_RELEASES)
224
+ return {
225
+ latestVersion: visible[0]?.version ?? null,
226
+ latestStableVersion: visible.find((release) => !release.prerelease)?.version ?? null,
227
+ checkedAt: new Date((options.now ?? Date.now)()).toISOString(),
228
+ releases: visible,
229
+ }
230
+ }
231
+
232
+ /** Read official versions, with a six-hour cache and offline fallback. Does not install anything. */
233
+ export async function checkComponentReleases({ dataRoot, force = false, now = Date.now, ...options }) {
234
+ if (!dataRoot) throw new TypeError('dataRoot is required')
235
+ const cached = await readComponentReleaseCache(dataRoot, { now })
236
+ const age = cached.attemptedAt ? now() - Date.parse(cached.attemptedAt) : Infinity
237
+ if (!force && age >= 0 && age < (cached.error ? FAILURE_TTL : CACHE_TTL)) return cached
238
+ if (checks.has(dataRoot)) return checks.get(dataRoot)
239
+ const pending = (async () => {
240
+ const result = { ...cached, attemptedAt: new Date(now()).toISOString(), components: { ...cached.components } }
241
+ const outcomes = await Promise.allSettled(['launcher', 'cli'].map((kind) => discoverComponent(kind, { ...options, now })))
242
+ const errors = []
243
+ for (let index = 0; index < outcomes.length; index += 1) {
244
+ const kind = index === 0 ? 'launcher' : 'cli'
245
+ const outcome = outcomes[index]
246
+ if (outcome.status === 'fulfilled') result.components[kind] = outcome.value
247
+ else errors.push(`${kind === 'launcher' ? 'Launcher' : 'CLI'}: ${outcome.reason?.message || 'Release check failed.'}`)
248
+ }
249
+ result.stale = errors.length > 0
250
+ result.error = errors.length ? errors.join(' ').slice(0, 600) : null
251
+ if (!errors.length) result.checkedAt = result.attemptedAt
252
+ try {
253
+ await writeJsonAtomic(componentReleaseCachePath(dataRoot), { schemaVersion: CACHE_SCHEMA, ...result })
254
+ } catch {
255
+ // Version checking must never prevent running already-installed components.
256
+ }
257
+ return result
258
+ })()
259
+ checks.set(dataRoot, pending)
260
+ try { return await pending } finally { if (checks.get(dataRoot) === pending) checks.delete(dataRoot) }
261
+ }
262
+
263
+ function parseChecksums(text) {
264
+ const hashes = new Map()
265
+ for (const line of text.replace(/^\uFEFF/, '').split(/\r?\n/)) {
266
+ if (!line.trim() || line.trimStart().startsWith('#')) continue
267
+ const match = line.match(/^([a-fA-F0-9]{64})\s+\*?([^\r\n]+?)\s*$/)
268
+ if (!match || !/^[A-Za-z0-9][A-Za-z0-9._+-]*$/.test(match[2])) {
269
+ fail('COMPONENT_CHECKSUM_INVALID', 'The official SHA256SUMS file contains an invalid entry.')
270
+ }
271
+ const hash = match[1].toLowerCase()
272
+ if (hashes.has(match[2]) && hashes.get(match[2]) !== hash) fail('COMPONENT_CHECKSUM_INVALID', 'The official SHA256SUMS file contains conflicting entries.')
273
+ hashes.set(match[2], hash)
274
+ }
275
+ if (!hashes.size) fail('COMPONENT_CHECKSUM_INVALID', 'The official SHA256SUMS file contains no checksums.')
276
+ return hashes
277
+ }
278
+
279
+ function assertDigest(asset, hash) {
280
+ if (asset.digest && asset.digest !== `sha256:${hash}`) fail('COMPONENT_CHECKSUM_MISMATCH', `GitHub and SHA256SUMS disagree for ${asset.name}.`)
281
+ }
282
+
283
+ /** Validate an already-verified component receipt without contacting GitHub. */
284
+ export function validateComponentRelease(kind, component) {
285
+ const source = sourceFor(kind)
286
+ if (!component || !validVersion(component.version)) fail('COMPONENT_VERSION_INVALID', 'Invalid saved component version.')
287
+ const { version } = component
288
+ const tag = `${source.prefix}${version}`
289
+ const files = requiredFiles(kind, version)
290
+ const inputs = kind === 'launcher' ? component.assets : [component.wheel, component.checksums]
291
+ if (!Array.isArray(inputs) || inputs.length !== files.length) fail('COMPONENT_ASSET_MISSING', 'Saved component receipt has an incomplete asset list.')
292
+ const assets = files.map((file) => {
293
+ const matches = inputs.filter((asset) => asset?.file === file)
294
+ if (matches.length !== 1) fail('COMPONENT_ASSET_MISSING', `Saved component receipt requires exactly one ${file} asset.`)
295
+ const asset = matches[0]
296
+ if (asset.url !== assetUrl(kind, tag, file) || !SHA256.test(asset.sha256 ?? '')) {
297
+ fail('COMPONENT_ASSET_UNTRUSTED', `Saved component asset ${file} has an invalid official URL or checksum.`)
298
+ }
299
+ return { file, url: asset.url, sha256: asset.sha256 }
300
+ })
301
+ if (kind === 'launcher') {
302
+ if (component.minimumJavaVersion !== '17.0.0' || component.runtimeApiContract !== 'foggy-runtime-api/v1') {
303
+ fail('COMPONENT_MANIFEST_INCOMPATIBLE', 'Saved Launcher receipt uses an unsupported Runtime API or Java requirement.')
304
+ }
305
+ return { version, minimumJavaVersion: '17.0.0', runtimeApiContract: 'foggy-runtime-api/v1', assets }
306
+ }
307
+ if (component.minimumPythonVersion !== '3.11.0') fail('COMPONENT_MANIFEST_INCOMPATIBLE', 'Saved CLI receipt uses an unsupported Python requirement.')
308
+ return { version, minimumPythonVersion: '3.11.0', wheel: assets[0], checksums: assets[1] }
309
+ }
310
+
311
+ async function verifiedJsonAsset(kind, tag, file, assets, hashes, options) {
312
+ const asset = verifiedAsset(kind, tag, file, assets)
313
+ const expected = hashes.get(file)
314
+ if (!expected) fail('COMPONENT_CHECKSUM_MISSING', `SHA256SUMS does not cover ${file}.`)
315
+ const payload = await requestText(asset.browser_download_url, { ...options, maxBytes: 256 * 1024 })
316
+ const actual = createHash('sha256').update(payload.bytes).digest('hex')
317
+ if (actual !== expected) fail('COMPONENT_CHECKSUM_MISMATCH', `Downloaded ${file} does not match SHA256SUMS.`)
318
+ assertDigest(asset, actual)
319
+ try { return JSON.parse(payload.text) } catch { fail('COMPONENT_MANIFEST_INVALID', `The official ${file} is invalid.`) }
320
+ }
321
+
322
+ /** Resolve a selected official tag to the existing versions.json component format. */
323
+ export async function resolveComponentRelease(kind, version, options = {}) {
324
+ const source = sourceFor(kind)
325
+ if (!validVersion(version)) fail('COMPONENT_VERSION_INVALID', 'Select a valid published component version.')
326
+ const tag = `${source.prefix}${version}`
327
+ const release = await requestJson(`https://api.github.com/repos/${source.repository}/releases/tags/${tag}`, options)
328
+ const normalized = normalizeRelease(kind, release)
329
+ if (!normalized || normalized.tag !== tag) fail('COMPONENT_RELEASE_INVALID', 'The requested official release was not found or is a draft.')
330
+ if (!normalized.installable) fail('COMPONENT_RELEASE_INCOMPLETE', normalized.unavailableReason)
331
+ const checksumAsset = verifiedAsset(kind, tag, 'SHA256SUMS', release.assets)
332
+ const checksumPayload = await requestText(checksumAsset.browser_download_url, { ...options, maxBytes: 256 * 1024 })
333
+ const checksumHash = createHash('sha256').update(checksumPayload.bytes).digest('hex')
334
+ assertDigest(checksumAsset, checksumHash)
335
+ const hashes = parseChecksums(checksumPayload.text)
336
+ const assets = requiredFiles(kind, version).map((file) => {
337
+ const asset = verifiedAsset(kind, tag, file, release.assets)
338
+ const hash = file === 'SHA256SUMS' ? checksumHash : hashes.get(file)
339
+ if (!SHA256.test(hash ?? '')) fail('COMPONENT_CHECKSUM_MISSING', `SHA256SUMS does not cover ${file}.`)
340
+ assertDigest(asset, hash)
341
+ return { file, url: asset.browser_download_url, sha256: hash }
342
+ })
343
+ if (kind === 'launcher') {
344
+ const manifest = await verifiedJsonAsset(kind, tag, 'runtime-launcher-manifest.json', release.assets, hashes, options)
345
+ const jar = assets[0]
346
+ if (manifest.schemaVersion !== 'foggy-runtime-launcher/v1' || manifest.releaseVersion !== version
347
+ || manifest.runtimeApiProfile !== true || manifest.releaseReady !== true
348
+ || manifest.jar?.file !== jar.file || manifest.jar?.sha256 !== jar.sha256) {
349
+ fail('COMPONENT_MANIFEST_INCOMPATIBLE', 'The selected Launcher does not declare a ready Runtime API launcher with matching artifacts.')
350
+ }
351
+ return { version, minimumJavaVersion: '17.0.0', runtimeApiContract: 'foggy-runtime-api/v1', assets }
352
+ }
353
+ // Older CLI releases do not all have a manifest. When published, verify it too.
354
+ if (release.assets.some((asset) => asset.name === 'release-manifest.json')) {
355
+ const manifest = await verifiedJsonAsset(kind, tag, 'release-manifest.json', release.assets, hashes, options)
356
+ if (manifest.schemaVersion !== 'foggy-runtime-cli-release/v1' || manifest.version !== version) {
357
+ fail('COMPONENT_MANIFEST_INCOMPATIBLE', 'The selected CLI release manifest does not match its version.')
358
+ }
359
+ const wheel = manifest.artifacts?.find((asset) => asset.file === assets[0].file)
360
+ if (!wheel || wheel.sha256 !== assets[0].sha256) fail('COMPONENT_MANIFEST_INCOMPATIBLE', 'The selected CLI manifest does not match its wheel checksum.')
361
+ }
362
+ return { version, minimumPythonVersion: '3.11.0', wheel: assets[0], checksums: assets[1] }
363
+ }