repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
extensions/lsp/scripts/registry.ts
Rawimport { 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<string, unknown>;
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<string, Record<string, { value: unknown; reason: string }>>;
};
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<string> {
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<void>,
previousText?: string,
): Promise<void> {
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<void>;
report?: (message: string) => void;
} = {},
): Promise<Registry> {
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);
}
}