@dsh-workbench/shared 0.3.10 → 1.0.0-beta.0

package/src/host/recipe.ts

@@ -0,0 +1,323 @@
+import type { CallOverrides, RecipeAuth, RecipeCalls, RequestRecipe } from '../contract/data.js';
+import { callsProblemOf, DEFAULT_RECIPE_MAX_BYTES, recipeProblemOf } from './recipe-rules.js';
+
+export interface RecipeDescription {
+  readonly method: string;
+  readonly url: string;
+  readonly body?: unknown;
+  readonly auth?:
+    | {
+        readonly source: string;
+        readonly place: string;
+        readonly name?: string;
+      }
+    | undefined;
+}
+
+
+function authOf(recipe: RequestRecipe): RecipeAuth {
+  return recipe.auth ?? { source: { kind: 'cookie' }, place: { in: 'cookie' } };
+}
+
+function needsToken(auth: RecipeAuth): boolean {
+  return auth.kind !== 'none' && auth.source.kind !== 'cookie';
+}
+
+function mergedHeaders(recipe: RequestRecipe, overrides: CallOverrides): Record<string, string> {
+  return { ...(recipe.request.headers ?? {}), ...(overrides.headers ?? {}) };
+}
+
+function mergedQuery(recipe: RequestRecipe, overrides: CallOverrides): Record<string, string> {
+  const query: Record<string, string> = {};
+  for (const [name, value] of Object.entries(recipe.request.query ?? {})) query[name] = String(value);
+  for (const [name, value] of Object.entries(overrides.query ?? {})) query[name] = String(value);
+  return query;
+}
+
+function baseUrlOf(recipe: RequestRecipe, overrides: CallOverrides): string {
+  const path = overrides.path ?? recipe.request.path;
+  return path.startsWith('/') ? `${recipe.origin}${path}` : path;
+}
+
+function urlOf(recipe: RequestRecipe, overrides: CallOverrides): string {
+  const url = new URL(baseUrlOf(recipe, overrides));
+  for (const [name, value] of Object.entries(mergedQuery(recipe, overrides))) {
+    url.searchParams.set(name, value);
+  }
+  return url.toString();
+}
+
+function responseOf(
+  recipe: RequestRecipe,
+  overrides: CallOverrides,
+): { kind: 'json' | 'text'; path: string | undefined; maxBytes: number } {
+  const base = recipe.response;
+  const extra = overrides.response ?? {};
+  return {
+    kind: extra.kind ?? base?.kind ?? 'json',
+    path: extra.path ?? base?.path,
+    maxBytes: extra.maxBytes ?? base?.maxBytes ?? DEFAULT_RECIPE_MAX_BYTES,
+  };
+}
+
+function bodyOf(recipe: RequestRecipe, overrides: CallOverrides): unknown {
+  return overrides.body !== undefined ? overrides.body : recipe.request.body;
+}
+
+function quote(value: string): string {
+  return JSON.stringify(value);
+}
+
+function literal(value: unknown): string {
+  return JSON.stringify(value);
+}
+
+function encodedBody(value: unknown): string {
+  return typeof value === 'string' ? literal(value) : `JSON.stringify(${literal(value)})`;
+}
+
+function tokenLines(recipe: RequestRecipe, auth: RecipeAuth): string[] {
+  if (!needsToken(auth)) return [];
+  const source = auth.kind === 'none' ? undefined : auth.source;
+  if (source === undefined) return [];
+  if (source.kind === 'cookieValue') {
+    return [
+      '  const cookie = (name) => {',
+      '    const hit = document.cookie.split("; ").find((one) => one.startsWith(name + "="));',
+      '    return hit === undefined ? "" : decodeURIComponent(hit.slice(name.length + 1));',
+      '  };',
+      `  const token = cookie(${quote(source.name)});`,
+      '  if (token === "") return { ok: false, code: "auth-failed", message: "页面里没有这个 cookie" };',
+    ];
+  }
+  if (source.kind === 'meta') {
+    return [
+      `  const meta = document.querySelector(${quote(`meta[name="${source.name}"]`)});`,
+      '  const token = meta === null ? "" : (meta.getAttribute("content") || "");',
+      '  if (token === "") return { ok: false, code: "auth-failed", message: "页面里没有这个 meta" };',
+    ];
+  }
+  if (source.kind === 'global') {
+    return [
+      `  const token = pick(globalThis, ${quote(source.path)});`,
+      '  if (typeof token !== "string" || token === "") return { ok: false, code: "auth-failed", message: "页面里没有这个全局变量" };',
+    ];
+  }
+  if (source.kind === 'storage') {
+    const store = source.area === 'local' ? 'localStorage' : 'sessionStorage';
+    const path = source.path === undefined ? '' : source.path;
+    return [
+      `  const raw = ${store}.getItem(${quote(source.key)});`,
+      '  let parsed = raw;',
+      '  try { parsed = raw === null ? null : JSON.parse(raw); } catch (error) { parsed = raw; }',
+      path === ''
+        ? '  const token = parsed;'
+        : `  const token = pick(parsed, ${quote(path)});`,
+      '  if (typeof token !== "string" || token === "") return { ok: false, code: "auth-failed", message: "页面里没有这个 token" };',
+    ];
+  }
+  if (source.kind === 'endpoint') {
+    const method = source.method ?? 'GET';
+    const hasBody = source.body !== undefined;
+    const endpointUrl = source.url.startsWith('/') ? `${recipe.origin}${source.url}` : source.url;
+    const lines = [
+      '  let pre;',
+      '  try {',
+      `    pre = await fetch(${quote(endpointUrl)}, { method: ${quote(method)}, credentials: "include", headers: { "content-type": "application/json" }${hasBody ? `, body: ${encodedBody(source.body)}` : ''} });`,
+      '  } catch (error) {',
+      '    return { ok: false, code: "fetch-failed", message: String(error) };',
+      '  }',
+      '  if (pre.status === 401 || pre.status === 403) return { ok: false, code: "not-logged-in" };',
+      '  const preText = await pre.text();',
+      '  if (!pre.ok) return { ok: false, code: "http-" + pre.status, message: preText.slice(0, 200) };',
+      '  let preJson;',
+      '  try { preJson = JSON.parse(preText); } catch (error) {',
+      '    return { ok: false, code: "shape", message: "换登录态时返回的不是 JSON" };',
+      '  }',
+      `  const token = pick(preJson, ${quote(source.path)});`,
+      '  if (typeof token !== "string" || token === "") return { ok: false, code: "auth-failed", message: "换登录态时没拿到 token" };',
+    ];
+    return lines;
+  }
+  return [];
+}
+
+function fetchLine(recipe: RequestRecipe, hasBody: boolean): string {
+  return `    res = await fetch(url, { method: ${quote(recipe.request.method)}, credentials: "include", headers${hasBody ? ', body' : ''} });`;
+}
+
+export function scriptOf(recipe: RequestRecipe, overrides: CallOverrides = {}): string {
+  const problem = recipeProblemOf(recipe, overrides);
+  if (problem !== undefined) throw new Error(problem);
+  const auth = authOf(recipe);
+  const body = bodyOf(recipe, overrides);
+  const contentType = recipe.request.contentType ?? 'json';
+  const place = auth.kind === 'none' ? undefined : auth.place;
+  const bodyPlace = place?.in === 'body' ? place : undefined;
+  const hasBody = body !== undefined || bodyPlace !== undefined;
+  const headers = mergedHeaders(recipe, overrides);
+  const headerNames = Object.keys(headers).map((name) => name.toLowerCase());
+  if (hasBody && !headerNames.includes('content-type')) {
+    headers['content-type'] = contentType === 'form' ? 'application/x-www-form-urlencoded' : 'application/json';
+  }
+  const url = urlOf(recipe, overrides);
+  const { kind: responseKind, path: responsePath, maxBytes } = responseOf(recipe, overrides);
+  const lines: string[] = [];
+  lines.push('(async () => {');
+  lines.push(`  if (location.origin !== ${quote(recipe.origin)}) return { ok: false, code: "not-on-site" };`);
+  lines.push(
+    '  const pick = (value, path) => path.split(".").reduce((one, key) => (one === null || one === undefined ? one : one[key]), value);',
+  );
+  lines.push(
+    '  const set = (target, path, value) => { const parts = path.split("."); let at = target; for (let index = 0; index < parts.length - 1; index += 1) { const key = parts[index]; if (at[key] === null || typeof at[key] !== "object") at[key] = {}; at = at[key]; } at[parts[parts.length - 1]] = value; return target; };',
+  );
+  lines.push(...tokenLines(recipe, auth));
+  lines.push(`  const headers = ${literal(headers)};`);
+  if (place?.in === 'header' && needsToken(auth)) {
+    lines.push(`  headers[${quote(place.name)}] = ${quote(place.prefix ?? '')} + token;`);
+  }
+  if (hasBody) {
+    if (contentType === 'form') {
+      lines.push(`  const body = new URLSearchParams(${literal(body ?? {})});`);
+      if (bodyPlace !== undefined) lines.push(`  body.set(${quote(bodyPlace.field)}, token);`);
+    } else {
+      lines.push(`  let body = ${literal(body ?? {})};`);
+      if (bodyPlace !== undefined) lines.push(`  set(body, ${quote(bodyPlace.field)}, token);`);
+      lines.push('  if (typeof body !== "string") body = JSON.stringify(body);');
+    }
+  }
+  lines.push(`  let url = ${quote(url)};`);
+  if (place?.in === 'query' && needsToken(auth)) {
+    lines.push(
+      `  url += (url.indexOf("?") === -1 ? "?" : "&") + ${quote(`${place.name}=`)} + encodeURIComponent(token);`,
+    );
+  }
+  lines.push('  let res;');
+  lines.push('  try {');
+  lines.push(fetchLine(recipe, hasBody));
+  lines.push('  } catch (error) {');
+  lines.push('    return { ok: false, code: "fetch-failed", message: String(error) };');
+  lines.push('  }');
+  lines.push('  const text = await res.text();');
+  lines.push(
+    `  if (new TextEncoder().encode(text).length > ${maxBytes}) return { ok: false, code: "too-large", message: "返回超过 ${Math.round(maxBytes / 1024)} KB" };`,
+  );
+  lines.push('  if (!res.ok) return { ok: false, code: "http-" + res.status, message: text.slice(0, 200) };');
+  if (responseKind === 'text') {
+    lines.push('  return { ok: true, text };');
+  } else {
+    lines.push('  let data;');
+    lines.push('  try {');
+    lines.push('    data = JSON.parse(text);');
+    lines.push('  } catch (error) {');
+    lines.push('    return { ok: false, code: "shape", message: "返回的不是 JSON（可能跳到登录页了）" };');
+    lines.push('  }');
+    if (responsePath === undefined) {
+      lines.push('  return { ok: true, data };');
+    } else {
+      lines.push(`  const value = pick(data, ${quote(responsePath)});`);
+      lines.push(
+        `  if (value === undefined) return { ok: false, code: "shape", message: "返回里没有 ${responsePath} 这一格" };`,
+      );
+      lines.push('  return { ok: true, data: value };');
+    }
+  }
+  lines.push('})()');
+  return lines.join('\n');
+}
+
+export function describeRecipe(recipe: RequestRecipe, overrides: CallOverrides = {}): RecipeDescription {
+  const problem = recipeProblemOf(recipe, overrides);
+  if (problem !== undefined) throw new Error(problem);
+  const auth = authOf(recipe);
+  const body = bodyOf(recipe, overrides);
+  const placement = auth.kind === 'none' ? undefined : auth.place;
+  const name =
+    placement === undefined || placement.in === 'cookie'
+      ? undefined
+      : placement.in === 'body'
+        ? placement.field
+        : placement.name;
+  return {
+    method: recipe.request.method,
+    url: urlOf(recipe, overrides),
+    ...(body === undefined ? {} : { body }),
+    ...(placement === undefined
+      ? {}
+      : {
+          auth: {
+            source: auth.kind === 'none' ? 'none' : auth.source.kind,
+            place: placement.in,
+            ...(name === undefined ? {} : { name }),
+          },
+        }),
+  };
+}
+
+
+export function scriptOfMany(recipe: RequestRecipe, calls: RecipeCalls): string {
+  const problem = callsProblemOf(recipe, calls);
+  if (problem !== undefined) throw new Error(problem);
+  if (recipe.request.method !== 'GET') throw new Error('批量读只认 GET，写一条一条走 submit');
+  const auth = authOf(recipe);
+  const place = auth.kind === 'none' ? undefined : auth.place;
+  if (place?.in === 'body') throw new Error('批量读不带 body 里的凭据');
+  const lines: string[] = [];
+  lines.push('(async () => {');
+  lines.push(`  if (location.origin !== ${quote(recipe.origin)}) return { ok: false, code: "not-on-site" };`);
+  lines.push(
+    '  const pick = (value, path) => path.split(".").reduce((one, key) => (one === null || one === undefined ? one : one[key]), value);',
+  );
+  lines.push(...tokenLines(recipe, auth));
+  lines.push(`  const headers = ${literal(recipe.request.headers ?? {})};`);
+  if (place?.in === 'header' && needsToken(auth)) {
+    lines.push(`  headers[${quote(place.name)}] = ${quote(place.prefix ?? '')} + token;`);
+  }
+  if (place?.in === 'query' && needsToken(auth)) {
+    lines.push(
+      `  const withToken = (url) => url + (url.indexOf("?") === -1 ? "?" : "&") + ${quote(`${place.name}=`)} + encodeURIComponent(token);`,
+    );
+  } else {
+    lines.push('  const withToken = (url) => url;');
+  }
+  lines.push('  const one = async (url, headers, kind, path, maxBytes) => {');
+  lines.push('    let res;');
+  lines.push('    try {');
+  lines.push('      res = await fetch(url, { method: "GET", credentials: "include", headers });');
+  lines.push('    } catch (error) {');
+  lines.push('      return { ok: false, code: "fetch-failed", message: String(error) };');
+  lines.push('    }');
+  lines.push('    const text = await res.text();');
+  lines.push(
+    '    if (new TextEncoder().encode(text).length > maxBytes) return { ok: false, code: "too-large", message: "返回超过 " + Math.round(maxBytes / 1024) + " KB" };',
+  );
+  lines.push('    if (!res.ok) return { ok: false, code: "http-" + res.status, message: text.slice(0, 200) };');
+  lines.push('    if (kind === "text") return { ok: true, text };');
+  lines.push('    let data;');
+  lines.push('    try {');
+  lines.push('      data = JSON.parse(text);');
+  lines.push('    } catch (error) {');
+  lines.push('      return { ok: false, code: "shape", message: "返回的不是 JSON（可能跳到登录页了）" };');
+  lines.push('    }');
+  lines.push('    if (path === null) return { ok: true, data };');
+  lines.push('    const value = pick(data, path);');
+  lines.push('    if (value === undefined) return { ok: false, code: "shape", message: "返回里没有 " + path + " 这一格" };');
+  lines.push('    return { ok: true, data: value };');
+  lines.push('  };');
+  lines.push('  const results = {};');
+  lines.push('  await Promise.all([');
+  for (const [name, call] of Object.entries(calls)) {
+    const extra = call.headers ?? {};
+    const headersArg =
+      Object.keys(extra).length === 0 ? 'headers' : `Object.assign({}, headers, ${literal(extra)})`;
+    const { kind, path, maxBytes } = responseOf(recipe, call);
+    const pathArg = path === undefined ? 'null' : quote(path);
+    lines.push(
+      `    one(withToken(${quote(urlOf(recipe, call))}), ${headersArg}, ${quote(kind)}, ${pathArg}, ${maxBytes}).then((result) => { results[${quote(name)}] = result; }),`,
+    );
+  }
+  lines.push('  ]);');
+  lines.push('  return { ok: true, results };');
+  lines.push('})()');
+  return lines.join('\n');
+}

package/src/host/shell-text.ts

@@ -1,10 +1,22 @@
 /**
- * 把一个值裹成 shell 里的单引号字面量（值里的单引号一并转义），保证元字符按字面量传递。
+ * 按目标平台把一个值裹成 shell 字面量：POSIX 用单引号，win32 用双引号（cmd 与 PowerShell 都认）。
  * @param value - 任意值；不是字符串的先 `String()`。
- * @returns 可安全拼进 `/bin/sh -c` 的一段文本 —— 含空格 / `$()` / `;` / 通配符的值都不会被当成语法。
+ * @param platform - 目标平台，默认当前 `process.platform`。
+ * @returns 可安全拼进该平台 shell 命令的一段文本；含空格 / 元字符的值不会被当成语法。
+ */
+export function quoteShellArgFor(value: unknown, platform: NodeJS.Platform = process.platform): string {
+  const text = String(value);
+  if (platform === 'win32') return `"${text.replace(/"/g, '\\"')}"`;
+  return `'${text.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * 按当前平台把值裹成 shell 字面量；跨平台代码要固定平台时用 `quoteShellArgFor`。
+ * @param value - 任意值；不是字符串的先 `String()`。
+ * @returns 可安全拼进当前平台 shell 命令的一段文本。
  */
 export function quoteShellArg(value: unknown): string {
-  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+  return quoteShellArgFor(value, process.platform);
 }
 
 /**

package/src/host/shell.ts

@@ -1,5 +1,6 @@
 import type { DshShell } from '../api/dsh.js';
 import { GIT_TIMEOUT_MS } from '../config/constants.js';
+import { quoteShellArg } from './shell-text.js';
 
 export interface ShellResult {
   readonly exitCode: number | null;
@@ -40,3 +41,11 @@ export async function runShell(
     truncated: result.stdout.truncated || result.stderr.truncated,
   };
 }
+
+export function backgroundPrefix(): readonly string[] {
+  return [quoteShellArg('env'), quoteShellArg('OPENCLI_WINDOW=background')];
+}
+
+export function backgroundLine(command: string, argv: readonly string[]): string {
+  return [...backgroundPrefix(), quoteShellArg(command), ...argv.map(quoteShellArg)].join(' ');
+}

package/src/host/spec.ts

@@ -0,0 +1,32 @@
+import path from 'node:path';
+
+const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+const VERSION = /^[a-zA-Z0-9][a-zA-Z0-9._+-]*$/;
+
+export interface NpmRef {
+  readonly name: string;
+  readonly version?: string;
+}
+
+export function isPackageName(value: string): boolean {
+  return value.length <= 214 && PACKAGE_NAME.test(value);
+}
+
+export function splitNpmSpec(spec: string): NpmRef | undefined {
+  const value = spec.trim();
+  const at = value.lastIndexOf('@');
+  const name = at > 0 ? value.slice(0, at) : value;
+  const version = at > 0 ? value.slice(at + 1) : '';
+  if (!isPackageName(name)) return undefined;
+  if (version !== '' && !VERSION.test(version)) return undefined;
+  return { name, ...(version === '' ? {} : { version }) };
+}
+
+export function localDirOf(spec: string): string | undefined {
+  const dir = spec.trim().replace(/^(?:file|link):/, '');
+  return path.isAbsolute(dir) ? dir : undefined;
+}
+
+export function refusalReason(): string {
+  return '这个包既不是工作台的模块，也不是 opencli 的插件，装了也用不上';
+}

package/src/host/supply-index.ts

@@ -0,0 +1,256 @@
+import type { ExtensionNeed, LibNeed, Need, SupplySource } from '../contract/needs.js';
+
+export interface SupplyDeclaration {
+  readonly id: string;
+  readonly needs?: readonly Need[];
+}
+
+export interface SupplyEntry {
+  readonly key: string;
+  readonly kind: 'extension' | 'lib';
+  readonly names: readonly string[];
+  readonly package: string;
+  readonly runtime?: string;
+  readonly sources: readonly SupplySource[];
+  readonly declarers: readonly string[];
+  readonly commands: readonly string[];
+  readonly conflicted: boolean;
+}
+
+export interface SupplyConflict {
+  readonly kind: 'source-mismatch' | 'name-mismatch';
+  readonly key: string;
+  readonly names: readonly string[];
+  readonly declarers: readonly string[];
+  readonly detail: string;
+}
+
+export interface SupplyIndex {
+  readonly entries: ReadonlyMap<string, SupplyEntry>;
+  readonly conflicts: readonly SupplyConflict[];
+  readonly problems: readonly string[];
+  readonly entryOf: (kind: 'extension' | 'lib', name: string) => SupplyEntry | undefined;
+  readonly sourcesOf: (kind: 'extension' | 'lib', name: string) => readonly SupplySource[];
+}
+
+interface MutableEntry {
+  key: string;
+  kind: 'extension' | 'lib';
+  package: string;
+  runtime?: string;
+  declared: boolean;
+  names: string[];
+  sources: SupplySource[];
+  declarers: string[];
+  commands: string[];
+  conflicted: boolean;
+}
+
+export function npmSourceOf(
+  sources: readonly SupplySource[] | undefined,
+): Extract<SupplySource, { kind: 'npm' }> | undefined {
+  return sources?.find((source): source is Extract<SupplySource, { kind: 'npm' }> => source.kind === 'npm');
+}
+
+function text(value: string | undefined): string {
+  return value === undefined ? '' : value.trim();
+}
+
+function conventionPackage(name: string): string {
+  return `opencli-plugin-${name}`;
+}
+
+function nativeSourcePackage(source: SupplySource): string {
+  if (source.kind === 'npm') return text(source.package);
+  if (source.kind === 'git') return `git:${text(source.url)}`;
+  return `local:${text(source.env) || text(source.path)}`;
+}
+
+function packageOf(need: ExtensionNeed | LibNeed): string {
+  if (need.kind === 'lib') return text(need.name);
+  const first = need.sources?.[0];
+  if (first === undefined) return conventionPackage(need.name);
+  if (first.kind === 'npm') {
+    const pkg = text(first.package);
+    return pkg === '' ? conventionPackage(need.name) : pkg;
+  }
+  return nativeSourcePackage(first);
+}
+
+function keyOf(kind: 'extension' | 'lib', pkg: string): string {
+  return `${kind}:${pkg}`;
+}
+
+function sourceCompatible(left: SupplySource, right: SupplySource): boolean {
+  if (left.kind !== right.kind) return false;
+  if (left.kind === 'npm' && right.kind === 'npm') {
+    if (text(left.package) !== '' && text(right.package) !== '' && text(left.package) !== text(right.package)) {
+      return false;
+    }
+    if (text(left.registryEnv) !== text(right.registryEnv)) return false;
+    const l = text(left.registryDefault);
+    const r = text(right.registryDefault);
+    return l === '' || r === '' || l === r;
+  }
+  if (left.kind === 'git' && right.kind === 'git') return text(left.url) === text(right.url);
+  if (left.kind === 'local' && right.kind === 'local') {
+    return text(left.env) === text(right.env) && text(left.path) === text(right.path);
+  }
+  return false;
+}
+
+function sourcesCompatible(left: readonly SupplySource[], right: readonly SupplySource[]): boolean {
+  if (left.length !== right.length) return false;
+  return left.every((source, index) => {
+    const other = right[index];
+    return other !== undefined && sourceCompatible(source, other);
+  });
+}
+
+function mergedSource(left: SupplySource, right: SupplySource): SupplySource {
+  if (left.kind === 'npm' && right.kind === 'npm') {
+    const pkg = text(left.package) === '' ? right.package : left.package;
+    const registryDefault = text(left.registryDefault) === '' ? right.registryDefault : left.registryDefault;
+    return {
+      ...left,
+      ...(pkg === undefined ? {} : { package: pkg }),
+      ...(registryDefault === undefined ? {} : { registryDefault }),
+    };
+  }
+  return left;
+}
+
+function mergeSources(entry: MutableEntry, sources: readonly SupplySource[]): boolean {
+  if (!entry.declared) {
+    entry.declared = true;
+    entry.sources = [...sources];
+    return true;
+  }
+  if (!sourcesCompatible(entry.sources, sources)) {
+    entry.conflicted = true;
+    return false;
+  }
+  entry.sources = entry.sources.map((source, index) => {
+    const other = sources[index];
+    return other === undefined ? source : mergedSource(source, other);
+  });
+  return true;
+}
+
+function sourceText(source: SupplySource): string {
+  if (source.kind === 'npm') {
+    return `${source.package === undefined ? '按包名约定' : source.package}（${source.registryEnv ?? '默认源'}）`;
+  }
+  if (source.kind === 'git') return `git:${source.url}`;
+  return `local:${source.env ?? source.path ?? ''}`;
+}
+
+function addDeclarer(entry: MutableEntry, unit: string, commands: readonly string[]): void {
+  if (!entry.declarers.includes(unit)) entry.declarers.push(unit);
+  for (const command of commands) if (!entry.commands.includes(command)) entry.commands.push(command);
+}
+
+export function buildSupplyIndex(declarations: readonly SupplyDeclaration[]): SupplyIndex {
+  const entries = new Map<string, MutableEntry>();
+  const byName = new Map<string, MutableEntry>();
+  const conflicts: SupplyConflict[] = [];
+
+  const ensure = (kind: 'extension' | 'lib', pkg: string): MutableEntry => {
+    const key = keyOf(kind, pkg);
+    const found = entries.get(key);
+    if (found !== undefined) return found;
+    const created: MutableEntry = {
+      key,
+      kind,
+      package: pkg,
+      declared: false,
+      names: [],
+      sources: [],
+      declarers: [],
+      commands: [],
+      conflicted: false,
+    };
+    entries.set(key, created);
+    return created;
+  };
+
+  for (const declaration of declarations) {
+    for (const need of declaration.needs ?? []) {
+      if (need.kind !== 'extension' && need.kind !== 'lib') continue;
+      const pkg = packageOf(need);
+      const entry = ensure(need.kind, pkg);
+      if (!entry.names.includes(need.name)) entry.names.push(need.name);
+      if (need.kind === 'extension') {
+        entry.runtime = need.runtime;
+        addDeclarer(entry, declaration.id, need.commands ?? []);
+      } else {
+        addDeclarer(entry, declaration.id, []);
+      }
+      const same = mergeSources(entry, need.sources ?? []);
+      if (!same) {
+        conflicts.push({
+          kind: 'source-mismatch',
+          key: entry.key,
+          names: [...entry.names],
+          declarers: [...entry.declarers],
+          detail:
+            `${entry.kind === 'extension' ? '插件' : '共用库'} ${entry.names.join('、')} 被 ` +
+            `${entry.declarers.join('、')} 声明成了不同的来源（` +
+            `${entry.sources.map(sourceText).join(' / ') || '无来源'}）`,
+        });
+      }
+      const nameKey = `${need.kind}:${need.name}`;
+      const seen = byName.get(nameKey);
+      if (seen !== undefined && seen.key !== entry.key) {
+        const detail =
+          `${need.kind === 'extension' ? '插件' : '共用库'} ${need.name} 来自不同的包：` +
+          `${seen.package} / ${entry.package}`;
+        entry.conflicted = true;
+        seen.conflicted = true;
+        conflicts.push({
+          kind: 'name-mismatch',
+          key: entry.key,
+          names: [need.name],
+          declarers: [...new Set([...seen.declarers, ...entry.declarers])],
+          detail,
+        });
+      } else if (seen === undefined) {
+        byName.set(nameKey, entry);
+      }
+    }
+  }
+
+  const deduped = new Map<string, SupplyConflict>();
+  for (const conflict of conflicts) {
+    deduped.set(`${conflict.kind}:${conflict.key}`, conflict);
+  }
+
+  const frozenEntries = new Map<string, SupplyEntry>();
+  for (const [key, entry] of entries) {
+    frozenEntries.set(key, {
+      key: entry.key,
+      kind: entry.kind,
+      names: [...entry.names],
+      package: entry.package,
+      ...(entry.runtime === undefined ? {} : { runtime: entry.runtime }),
+      sources: entry.sources.map((source) => ({ ...source })),
+      declarers: [...entry.declarers],
+      commands: [...entry.commands],
+      conflicted: entry.conflicted,
+    });
+  }
+
+  const entryOf = (kind: 'extension' | 'lib', name: string): SupplyEntry | undefined =>
+    byName.get(`${kind}:${name}`);
+
+  return {
+    entries: frozenEntries,
+    conflicts: [...deduped.values()],
+    problems: [...deduped.values()].map((conflict) => conflict.detail),
+    entryOf,
+    sourcesOf: (kind, name) => {
+      const entry = entryOf(kind, name);
+      return entry === undefined || entry.conflicted ? [] : entry.sources;
+    },
+  };
+}