import { createHash, randomUUID } from "node:crypto"; import { readFile, rename, unlink, writeFile } from "node:fs/promises"; import { dirname, join } from "node:path"; import { fileURLToPath, pathToFileURL } from "node:url"; import { parse } from "smol-toml"; type Data = Record; export type Profile = { id: string; command: string; args: string[]; language: string; extensions: string[]; roots: string[]; initializationOptions: Data; settings: Data; provenance?: Data; }; export type Registry = { schemaVersion: 1; profiles: Profile[] }; export type Policy = { schemaVersion: 1; revision: string; sha256: string; licenseSha256: string; selections: { id: string; language: string; extensions: string[] }[]; previousSource: Profile[]; overrides: Record>; }; const fields = [ "command", "args", "language", "extensions", "roots", "initializationOptions", "settings", ] as const; const limit = 2_000_000; const equal = (a: unknown, b: unknown) => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b)); function canonical(value: unknown): unknown { if (Array.isArray(value)) return value.map(canonical); if (value && typeof value === "object") return Object.fromEntries( Object.entries(value) .sort(([a], [b]) => a.localeCompare(b, "en")) .map(([k, v]) => [k, canonical(v)]), ); return value; } export function serialize(value: unknown): string { // Keep bounded string lists compact, matching repository JSON formatting. const pretty = JSON.stringify(value, null, "\t"); return `${pretty.replace( /\[\n(?:\t+"(?:[^"\\]|\\.)*",?\n)+\t*\]/g, (array, offset: number) => { const compact = `[${(JSON.parse(array) as string[]).map((v) => JSON.stringify(v)).join(", ")}]`; const line = pretty.slice(pretty.lastIndexOf("\n", offset) + 1, offset); return line.replaceAll("\t", " ").length + compact.length <= 80 ? compact : array; }, )}\n`; } export const digest = (value: string): string => createHash("sha256").update(value).digest("hex"); function object(value: unknown): Data { if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Expected catalog object"); return value as Data; } function strings(value: unknown): string[] { if ( !Array.isArray(value) || value.length > 100 || !value.every((v) => typeof v === "string" && v.length < 1024) ) throw new Error("Expected bounded string list"); return value; } function safe(value: unknown, depth = 0): void { if (depth > 12) throw new Error("Catalog nesting exceeds limit"); if ( typeof value === "string" && (value.length > 4096 || /[\x00-\x1f$%{}~`<>]|(?:^|[=\s])(?:\/|[A-Za-z]:[\\/])/.test(value)) ) throw new Error(`Unsafe catalog value: ${JSON.stringify(value)}`); if (Array.isArray(value)) { if (value.length > 100) throw new Error("Catalog list exceeds limit"); for (const v of value) safe(v, depth + 1); } else if (value && typeof value === "object") { if (Object.keys(value).length > 100) throw new Error("Catalog object exceeds limit"); for (const [k, v] of Object.entries(value)) { if (["__proto__", "constructor", "prototype"].includes(k)) throw new Error("Unsafe catalog key"); safe(k, depth + 1); safe(v, depth + 1); } } else if ( value !== null && !["string", "number", "boolean"].includes(typeof value) ) throw new Error("Invalid catalog data"); } export function validate(profile: Profile): void { if ( !/^[a-z][a-z0-9-]*$/.test(profile.id) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(profile.command) || !/^[a-z][a-z0-9]*$/.test(profile.language) ) throw new Error("Invalid profile identity or executable"); for (const field of fields) safe(profile[field]); strings(profile.args); if ( !strings(profile.extensions).length || !profile.extensions.every((v) => /^\.[a-z0-9]+$/.test(v)) ) throw new Error("Invalid extensions"); if ( !strings(profile.roots).length || !profile.roots.every( (v) => /^[a-zA-Z0-9_.-]+$/.test(v) && v !== "." && v !== "..", ) ) throw new Error("Invalid root markers"); object(profile.initializationOptions); object(profile.settings); } /** Helix config is initializationOptions, not workspace/didChangeConfiguration settings. */ export function derive(toml: string, policy: Policy): Profile[] { if (Buffer.byteLength(toml) > limit) throw new Error("Catalog too large"); const source = parse(toml); const servers = object(source["language-server"]); if (!Array.isArray(source["language"])) throw new Error("Missing languages"); return policy.selections.map((selection) => { const server = object(servers[selection.id]); const languages = (source["language"] as unknown[]) .map(object) .filter((v) => v["name"] === selection.language); const language = languages[0]; if (languages.length !== 1 || !language) throw new Error(`Missing/duplicate language ${selection.language}`); const associated = language["language-servers"]; if ( !Array.isArray(associated) || !associated.some( (v) => v === selection.id || (v && typeof v === "object" && object(v)["name"] === selection.id), ) ) throw new Error(`Server association missing: ${selection.id}`); const fileTypes = language["file-types"]; if ( !Array.isArray(fileTypes) || !selection.extensions.every((v) => fileTypes.includes(v.slice(1))) ) throw new Error(`Unsupported selected extension: ${selection.id}`); // Editor-only env, formatter, debugger, hints/actions are never interpreted or executed. if (server["env"] !== undefined) throw new Error(`Unreviewed launch environment: ${selection.id}`); const result: Profile = { id: selection.id, command: server["command"] as string, args: strings(server["args"] ?? []), language: (language["language-id"] ?? language["name"]) as string, extensions: selection.extensions, roots: strings(language["roots"] ?? []), initializationOptions: object(server["config"] ?? {}), settings: {}, }; // Roots may be supplied by an explicit reviewed local override (clangd). if (typeof result.command !== "string") throw new Error("Missing command"); for (const field of fields) safe(result[field]); return result; }); } export function merge( fresh: Profile[], policy: Policy, current?: Registry, ): Registry { const conflicts: string[] = []; const profiles = fresh.map((upstream) => { const previous = policy.previousSource.find((p) => p.id === upstream.id); if (!previous) throw new Error(`Missing previous source: ${upstream.id}`); const local = current?.profiles.find((p) => p.id === upstream.id); const result = { ...upstream }; const overrides = policy.overrides[upstream.id] ?? {}; for (const key of Object.keys(overrides)) if (!(fields as readonly string[]).includes(key)) throw new Error(`Unknown override field: ${key}`); for (const field of fields) { const override = overrides[field]; if (override && !override.reason?.trim()) throw new Error(`Missing override reason: ${upstream.id}.${field}`); const snapshotValue = local ? local[field] : previous[field]; const snapshotChanged = !!local && !equal(snapshotValue, previous[field]); const localValue = override && !snapshotChanged ? override.value : snapshotValue; // Both explicit overrides and direct reviewed snapshot edits are local decisions. const changedUpstream = !equal(upstream[field], previous[field]); const changedLocal = !equal(localValue, previous[field]) || !!override; if ( changedUpstream && changedLocal && !equal(localValue, upstream[field]) ) conflicts.push( `${upstream.id}.${field}: previous=${JSON.stringify(previous[field])} local=${JSON.stringify(localValue)} fresh=${JSON.stringify(upstream[field])}`, ); (result as unknown as Data)[field] = changedLocal ? localValue : upstream[field]; // A newly edited policy override must not silently overwrite a direct snapshot edit. if (override && snapshotChanged && !equal(localValue, override.value)) conflicts.push( `${upstream.id}.${field}: snapshot differs from explicit override; reconcile manually`, ); } validate(result); result.provenance = { url: `https://github.com/helix-editor/helix/blob/${policy.revision}/languages.toml`, revision: policy.revision, license: "MPL-2.0", review: "Curated Helix launch/language data; editor preferences omitted through reviewed local overrides.", overrides: Object.fromEntries( Object.entries(overrides).map(([key, value]) => [key, value.reason]), ), }; return result; }); if (conflicts.length) throw new Error(`Registry conflicts:\n${conflicts.join("\n")}`); return { schemaVersion: 1, profiles }; } async function fetchPinned(url: string, signal: AbortSignal): Promise { const response = await fetch(url, { signal, redirect: "error" }); if (!response.ok || !response.body) throw new Error(`Catalog fetch failed: ${response.status}`); const chunks: Uint8Array[] = []; let size = 0; for await (const chunk of response.body) { size += chunk.length; if (size > limit) throw new Error("Catalog too large"); chunks.push(chunk); } return Buffer.concat(chunks).toString("utf8"); } /** Same-directory temporary + rename: no partially written runtime snapshot is visible. */ export async function publish( path: string, content: string, signal: AbortSignal, beforeRename?: () => Promise, previousText?: string, ): Promise { const temporary = join(dirname(path), `.servers-${randomUUID()}.tmp`); try { signal.throwIfAborted(); await writeFile(temporary, content, { flag: "wx", signal }); await beforeRename?.(); signal.throwIfAborted(); if ( previousText !== undefined && (await readFile(path, "utf8")) !== previousText ) throw new Error("Registry changed during refresh"); signal.throwIfAborted(); await rename(temporary, path); } finally { await unlink(temporary).catch((error: NodeJS.ErrnoException) => { if (error.code !== "ENOENT") throw error; }); } } export async function refresh( directory: string, options: { signal?: AbortSignal; fetchText?: typeof fetchPinned; beforeRename?: () => Promise; report?: (message: string) => void; } = {}, ): Promise { const signal = options.signal ?? AbortSignal.timeout(30_000); const policy = JSON.parse( await readFile(join(directory, "policy.json"), "utf8"), ) as Policy; if ( policy.schemaVersion !== 1 || !/^[0-9a-f]{40}$/.test(policy.revision) || policy.selections.length !== 3 || new Set(policy.selections.map((s) => s.id)).size !== 3 ) throw new Error("Invalid pinned source policy"); const base = `https://raw.githubusercontent.com/helix-editor/helix/${policy.revision}`; const get = options.fetchText ?? fetchPinned; const [toml, license] = await Promise.all([ get(`${base}/languages.toml`, signal), get(`${base}/LICENSE`, signal), ]); if ( digest(toml) !== policy.sha256 || digest(license) !== policy.licenseSha256 || !license.startsWith("Mozilla Public License Version 2.0") ) throw new Error("Pinned source/license integrity mismatch"); const notice = await readFile(join(directory, "HELIX-LICENSE"), "utf8"); if (notice !== license) throw new Error("Packaged Helix license differs from pinned source"); const path = join(directory, "servers.json"); const previousText = await readFile(path, "utf8"); const current = JSON.parse(previousText) as Registry; if (current.schemaVersion !== 1 || !Array.isArray(current.profiles)) throw new Error("Expected reviewed schemaVersion 1 registry"); const result = merge(derive(toml, policy), policy, current); const content = serialize(result); for (const p of result.profiles) for (const field of [...fields, "provenance"] as const) { const old = current.profiles.find((v) => v.id === p.id)?.[field]; if (!equal(old, p[field])) options.report?.( `${p.id}.${field}: ${JSON.stringify(old)} -> ${JSON.stringify(p[field])}`, ); } signal.throwIfAborted(); // Detect edits at the publication boundary; maintainers must still serialize refreshes. if (content !== previousText) await publish(path, content, signal, options.beforeRename, previousText); options.report?.( content === previousText ? "Registry unchanged" : "Registry refreshed; review diff before committing", ); return result; } if ( process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href ) { const controller = new AbortController(); const cancel = () => controller.abort(new Error("Registry refresh interrupted")); process.once("SIGINT", cancel); process.once("SIGTERM", cancel); const timeout = setTimeout(cancel, 30_000); try { await refresh(fileURLToPath(new URL("../registry/", import.meta.url)), { signal: controller.signal, report: console.log, }); } catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; } finally { clearTimeout(timeout); process.removeListener("SIGINT", cancel); process.removeListener("SIGTERM", cancel); } }