@dsh-workbench/shared 1.1.5 → 1.1.7

package/src/host/market-index.ts

@@ -1,28 +1,40 @@
-import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
 import type {
-  DiscoverFilter,
-  IndexSourceSpec,
   MarketIndex,
   MarketIndexEntry,
-  MarketIndexParse,
   MarketIndexProblem,
-  MarketIndexSource,
   MarketIndexVersion,
-  MarketLocalizedText,
-  MarketSourceConfig,
 } from '../contract/protocol/market-index.js';
-import { MARKET_INDEX_FORMAT } from '../contract/protocol/market-index.js';
-import { marketText } from '../lib/market-index.js';
-import { compareVersions, isValidVersion } from './version.js';
+import { MARKET_INDEX_DIR, MARKET_INDEX_FORMAT } from '../contract/protocol/market-index.js';
 
-export { marketBranchOk, marketInstallTarget, marketText } from '../lib/market-index.js';
-
-export const MARKET_INDEX_SEED = '{\n  "format": 1,\n  "plugins": []\n}\n';
+import type {
+  MarketDocFields,
+  MarketEntryDoc,
+  MarketEntryFile,
+  MarketIndexAssemble,
+  MarketMetaDoc,
+  MarketVersionDoc,
+} from './market-index-doc.js';
+import {
+  marketEntryPath,
+  parseMarketEntryDoc,
+  parseMarketIndexJson,
+  sortMarketVersions,
+} from './market-index-parse.js';
+
+export const MARKET_ENTRIES_README_LINES: readonly string[] = [
+  '# 索引目录',
+  '',
+  '一个包一个目录，一个版本一个文件：`market/<包名>/<版本>.json`；产物在 `artifacts/<包名>/<版本>/`。',
+  '',
+  '`meta-<epoch>-<随机后缀>.json` 是只改标题 / 署名 / 说明时追加的元数据快照，读取时按 epoch 取最新的一份。',
+];
 
 export const MARKET_INDEX_README_LINES: readonly string[] = [
   '# 模块市场索引',
   '',
-  '这个仓库给 DeepSeek Harness 工作台当模块市场索引：`market.json`（format 1）列出可安装的模块与版本。',
+  '这个仓库给 DeepSeek Harness 工作台当模块市场索引：条目在 `market/<包名>/<版本>.json`，产物在 `artifacts/<包名>/<版本>/`。',
   '',
   '## 发布模块',
   '',
@@ -32,9 +44,10 @@ export const MARKET_INDEX_README_LINES: readonly string[] = [
   'dsh-wb-module release --index <本仓库地址> --index-policy artifacts-in-repo',
   '```',
   '',
-  '产物会提交到 `packages/<包名>/`（带 scope 时是 `packages/@scope/名字/`），并更新 `market.json`。',
+  '产物会提交到 `artifacts/<包名>/<版本>/`，条目提交到 `market/<包名>/<版本>.json`。',
+  '发布只新增文件、不改已有文件，两台机器同时发也不会冲突；老条目的 `packages/<包名>/` 路径继续可用。',
   '',
-  '一个包名归第一次发布的人（`market.json` 里的 `owner`）。换一个署名发同名会被拒；要换人，先把这一条的 `owner` 改成新的人。',
+  '一个包名归第一次发布的人（条目文件里的 `owner`）。换一个署名发同名会被拒；要换人，先把这一条的 `owner` 改成新的人。',
   '同一个市场里，一个模块 id（`metadata.unit`）只能被一个条目使用；另一个包名想用同一个 id / 产物目录也会被拒。',
   '',
   '## 使用这个索引',
@@ -42,373 +55,165 @@ export const MARKET_INDEX_README_LINES: readonly string[] = [
   '在工作台的「模块市场 → 发现」里添加本仓库地址，即可浏览与安装。',
   '',
 ];
+export { marketBranchOk, marketInstallTarget, marketText } from '../lib/market-index.js';
+export type {
+  MarketEntryDoc,
+  MarketEntryDocParse,
+  MarketEntryFile,
+  MarketIndexAssemble,
+  MarketMetaDoc,
+  MarketVersionDoc,
+} from './market-index-doc.js';
+export {
+  compareSemver,
+  filterMarketIndex,
+  gitUrlOk,
+  httpUrlProblem,
+  marketEntryLabels,
+  marketEntryPath,
+  marketMetaPath,
+  marketSourceKey,
+  parseMarketEntryDoc,
+  parseMarketIndex,
+  parseMarketIndexJson,
+  parseSourceConfig,
+  sortMarketVersions,
+  upsertMarketEntry,
+} from './market-index-parse.js';
+export type { SourceConfigParse } from './market-index-parse.js';
 
-const NPM_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
-const GIT_COMMIT = /^[0-9a-f]{40}$/;
-const MAX_ICON_CHARS = 32 * 1024;
-
-function asRecord(value: unknown): Readonly<Record<string, unknown>> | undefined {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-    ? (value as Readonly<Record<string, unknown>>)
-    : undefined;
-}
-
-function asText(value: unknown): string {
-  return typeof value === 'string' ? value.trim() : '';
-}
-
-function asTextArray(value: unknown): string[] {
-  return Array.isArray(value)
-    ? value.flatMap((item) => (typeof item === 'string' && item.trim() !== '' ? [item.trim()] : []))
-    : [];
-}
-
-function asLocalized(value: unknown): MarketLocalizedText | undefined {
-  const record = asRecord(value);
-  if (record === undefined) return undefined;
-  const zh = asText(record['zh']);
-  const en = asText(record['en']);
-  return zh === '' && en === '' ? undefined : { ...(zh === '' ? {} : { zh }), ...(en === '' ? {} : { en }) };
-}
 
 function problem(kind: MarketIndexProblem['kind'], detail: string, at?: string): MarketIndexProblem {
   return { kind, detail, ...(at === undefined ? {} : { at }) };
 }
 
-export function compareSemver(left: string, right: string): number | undefined {
-  return compareVersions(left, right);
-}
-
-function sourceOf(raw: unknown, at: string): MarketIndexSource | MarketIndexProblem {
-  const record = asRecord(raw);
-  if (record === undefined) return problem('source', 'source 必须是一个对象', at);
-  if (record['type'] === 'npm') {
-    const registry = record['registry'];
-    if (registry !== undefined && asText(registry) === '') {
-      return problem('source', 'npm source 的 registry 必须是非空字符串', at);
-    }
-    return { type: 'npm', ...(registry === undefined ? {} : { registry: asText(registry) }) };
-  }
-  if (record['type'] === 'git') {
-    const url = asText(record['url']);
-    const commit = asText(record['commit']);
-    if (url === '') return problem('source', 'git source 缺 url', at);
-    if (!GIT_COMMIT.test(commit)) {
-      return problem('git-commit', `git source 的 commit 必须是 40 位小写 SHA（现在是 ${JSON.stringify(commit)}）`, at);
-    }
-    const path = record['path'];
-    return {
-      type: 'git',
-      url,
-      commit,
-      ...(path === undefined || asText(path) === '' ? {} : { path: asText(path) }),
-    };
-  }
-  return problem('source', 'source.type 只能是 npm 或 git', at);
-}
-
-function versionOf(raw: unknown, at: string): MarketIndexVersion | MarketIndexProblem {
-  const record = asRecord(raw);
-  if (record === undefined) return problem('version', '版本必须是一个对象', at);
-  const version = asText(record['version']);
-  if (!isValidVersion(version)) return problem('version', `版本号不是合法 SemVer：${JSON.stringify(version)}`, at);
-  const source = sourceOf(record['source'], `${at}.source`);
-  if ('kind' in source) return source;
-  const timestamp = record['publishTimestamp'];
-  if (timestamp !== undefined && (!Number.isInteger(timestamp) || (timestamp as number) < 0)) {
-    return problem('timestamp', 'publishTimestamp 必须是 Unix 秒整数', at);
-  }
-  const engines = asRecord(record['engines']);
-  const dsh = engines === undefined ? '' : asText(engines['dsh']);
+function docFieldsFromEntry(entry: MarketIndexEntry): MarketDocFields {
   return {
-    version,
-    source,
-    ...(timestamp === undefined ? {} : { publishTimestamp: timestamp as number }),
-    ...(dsh === '' ? {} : { engines: { dsh } }),
+    name: entry.name,
+    ...(entry.title === undefined ? {} : { title: entry.title }),
+    ...(entry.description === undefined ? {} : { description: entry.description }),
+    ...(entry.author === undefined ? {} : { author: entry.author }),
+    ...(entry.owner === undefined ? {} : { owner: entry.owner }),
+    ...(entry.homepage === undefined ? {} : { homepage: entry.homepage }),
+    ...(entry.icon === undefined ? {} : { icon: entry.icon }),
+    ...(entry.metadata === undefined ? {} : { metadata: entry.metadata }),
   };
 }
 
-function versionsOf(raw: unknown, at: string): readonly MarketIndexVersion[] | MarketIndexProblem {
-  if (!Array.isArray(raw) || raw.length === 0) return problem('versions', 'versions 必须是非空数组', at);
-  const versions: MarketIndexVersion[] = [];
-  const seen = new Set<string>();
-  for (const [index, item] of raw.entries()) {
-    const parsed = versionOf(item, `${at}[${String(index)}]`);
-    if ('kind' in parsed) return parsed;
-    if (seen.has(parsed.version)) return problem('versions', `版本重复：${parsed.version}`, at);
-    seen.add(parsed.version);
-    versions.push(parsed);
-  }
-  for (let index = 1; index < versions.length; index += 1) {
-    const order = compareSemver(versions[index - 1]?.version ?? '', versions[index]?.version ?? '');
-    if (order === undefined || order < 0) {
-      return problem('version-order', 'versions 必须按 SemVer 降序', at);
-    }
-  }
-  return versions;
-}
-
-function iconProblem(icon: string): MarketIndexProblem | undefined {
-  if (icon.length > MAX_ICON_CHARS) return problem('icon', 'icon 超过 32 KiB');
-  if (icon.startsWith('data:image/')) return icon.includes(';base64,') ? undefined : problem('icon', 'data URL 必须是 base64');
-  if (/^https?:\/\//i.test(icon)) return undefined;
-  return problem('icon', 'icon 只能是 base64 data URL 或 http(s) URL');
-}
-
-const MAX_OWNER_CHARS = 200;
-const UNIT_ID = /^[a-z][a-z0-9-]*$/;
-
-function ownerProblem(owner: string): MarketIndexProblem | undefined {
-  if (/[\r\n]/u.test(owner)) return problem('owner', 'owner 只能是一行署名');
-  if (owner.length > MAX_OWNER_CHARS) return problem('owner', 'owner 超过 200 字');
-  return undefined;
-}
-
-function metadataOf(raw: unknown): MarketIndexEntry['metadata'] {
-  const record = asRecord(raw);
-  if (record === undefined) return undefined;
-  const workbench = record['workbench'] === true;
-  const unit = asText(record['unit']);
-  const category = asText(record['category']);
-  const labels = asTextArray(record['labels']);
-  const keywords = asTextArray(record['keywords']);
-  const sortKeysRecord = asRecord(record['sortKeys']);
-  const sortKeys =
-    sortKeysRecord === undefined
-      ? undefined
-      : Object.fromEntries(
-          Object.entries(sortKeysRecord).flatMap(([key, value]) =>
-            typeof value === 'string' || typeof value === 'number' ? [[key, value] as const] : [],
-          ),
-        );
-  return {
-    ...(workbench ? { workbench: true } : {}),
-    ...(unit === '' ? {} : { unit }),
-    ...(category === '' ? {} : { category }),
-    ...(labels.length === 0 ? {} : { labels }),
-    ...(keywords.length === 0 ? {} : { keywords }),
-    ...(sortKeys === undefined || Object.keys(sortKeys).length === 0 ? {} : { sortKeys }),
-  };
+export function marketVersionDocOf(entry: MarketIndexEntry, version: MarketIndexVersion): MarketVersionDoc {
+  return { ...docFieldsFromEntry(entry), ...version };
 }
 
-function entryOf(raw: unknown, at: string): MarketIndexEntry | MarketIndexProblem {
-  const record = asRecord(raw);
-  if (record === undefined) return problem('plugin', '插件条目必须是对象', at);
-  const name = asText(record['name']);
-  if (name === '' || name.length > 214 || !NPM_NAME.test(name)) {
-    return problem('name', `不是合法 npm 包名：${JSON.stringify(name)}`, at);
-  }
-  const versions = versionsOf(record['versions'], `${at}.versions`);
-  if ('kind' in versions) return versions;
-  const icon = asText(record['icon']);
-  if (icon !== '') {
-    const badIcon = iconProblem(icon);
-    if (badIcon !== undefined) return badIcon;
-  }
-  const title = asLocalized(record['title']);
-  const description = asLocalized(record['description']);
-  const author = asText(record['author']);
-  const owner = asText(record['owner']);
-  if (owner !== '') {
-    const badOwner = ownerProblem(owner);
-    if (badOwner !== undefined) return badOwner;
-  }
-  const homepage = asText(record['homepage']);
-  const metadata = metadataOf(record['metadata']);
-  if (metadata?.unit !== undefined && !UNIT_ID.test(metadata.unit)) {
-    return problem('unit', `metadata.unit 只能是小写字母开头的 a-z0-9-（现在是 ${JSON.stringify(metadata.unit)}）`, at);
-  }
-  return {
-    name,
-    versions,
-    ...(title === undefined ? {} : { title }),
-    ...(description === undefined ? {} : { description }),
-    ...(author === '' ? {} : { author }),
-    ...(owner === '' ? {} : { owner }),
-    ...(homepage === '' ? {} : { homepage }),
-    ...(icon === '' ? {} : { icon }),
-    ...(metadata === undefined ? {} : { metadata }),
-  };
+export function marketMetaDocOf(entry: MarketIndexEntry, epoch: number, at: number): MarketMetaDoc {
+  return { ...docFieldsFromEntry(entry), epoch, publishTimestamp: at };
 }
 
-export function parseMarketIndex(raw: unknown): MarketIndexParse {
-  const record = asRecord(raw);
-  if (record === undefined) return { ok: false, problems: [problem('not-object', '索引必须是一个 JSON 对象')] };
-  if (record['format'] !== MARKET_INDEX_FORMAT) {
-    return {
-      ok: false,
-      problems: [problem('format', `format 必须是 ${String(MARKET_INDEX_FORMAT)}（现在是 ${JSON.stringify(record['format'])}）`)],
-    };
-  }
-  const plugins = record['plugins'];
-  if (!Array.isArray(plugins)) return { ok: false, problems: [problem('plugins', 'plugins 必须是数组')] };
-  const entries: MarketIndexEntry[] = [];
+export function assembleMarketIndex(files: readonly MarketEntryFile[]): MarketIndexAssemble {
   const problems: MarketIndexProblem[] = [];
-  const seen = new Set<string>();
-  for (const [index, item] of plugins.entries()) {
-    const parsed = entryOf(item, `plugins[${String(index)}]`);
-    if ('kind' in parsed) {
-      problems.push(parsed);
+  interface Group {
+    versions: Map<string, MarketIndexVersion>;
+    meta: { epoch: number; at: number; path: string; doc: MarketEntryDoc } | undefined;
+    fallback: { at: number; path: string; doc: MarketEntryDoc } | undefined;
+  }
+  const groups = new Map<string, Group>();
+  const ordered = [...files].sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0));
+  for (const file of ordered) {
+    let raw: unknown;
+    try {
+      raw = JSON.parse(file.text) as unknown;
+    } catch (error) {
+      problems.push(
+        problem('not-json', `JSON 解析失败：${error instanceof Error ? error.message : String(error)}`, file.path),
+      );
       continue;
     }
-    if (seen.has(parsed.name)) {
-      problems.push(problem('duplicate-name', `插件名重复：${parsed.name}`, `plugins[${String(index)}]`));
+    const parsed = parseMarketEntryDoc(raw);
+    if (!parsed.ok) {
+      for (const one of parsed.problems) problems.push({ ...one, at: file.path });
       continue;
     }
-    seen.add(parsed.name);
-    entries.push(parsed);
+    const doc = parsed.doc;
+    const group =
+      groups.get(doc.name) ?? { versions: new Map<string, MarketIndexVersion>(), meta: undefined, fallback: undefined };
+    const at = doc.publishTimestamp ?? 0;
+    if ('version' in doc) {
+      if (group.versions.has(doc.version)) {
+        problems.push(problem('duplicate-version', `版本重复：${doc.version}`, file.path));
+      }
+      group.versions.set(doc.version, {
+        version: doc.version,
+        source: doc.source,
+        ...(doc.publishTimestamp === undefined ? {} : { publishTimestamp: doc.publishTimestamp }),
+        ...(doc.engines === undefined ? {} : { engines: doc.engines }),
+      });
+      const newerFallback =
+        group.fallback === undefined ||
+        at > group.fallback.at ||
+        (at === group.fallback.at && file.path > group.fallback.path);
+      if (newerFallback) group.fallback = { at, path: file.path, doc };
+    } else {
+      const epoch = doc.epoch ?? 0;
+      const newer =
+        group.meta === undefined ||
+        epoch > group.meta.epoch ||
+        (epoch === group.meta.epoch && at > group.meta.at) ||
+        (epoch === group.meta.epoch && at === group.meta.at && file.path > group.meta.path);
+      if (newer) group.meta = { epoch, at, path: file.path, doc };
+    }
+    groups.set(doc.name, group);
   }
   if (problems.length > 0) return { ok: false, problems };
-  const title = asLocalized(record['title']);
-  const description = asLocalized(record['description']);
-  const metadata = asRecord(record['metadata']);
-  return {
-    ok: true,
-    index: {
-      format: MARKET_INDEX_FORMAT,
-      plugins: entries,
-      ...(title === undefined ? {} : { title }),
-      ...(description === undefined ? {} : { description }),
-      ...(metadata === undefined ? {} : { metadata: metadata as MarketIndex['metadata'] }),
-    },
-  };
-}
-
-export function parseMarketIndexJson(text: string): MarketIndexParse {
-  try {
-    return parseMarketIndex(JSON.parse(text) as unknown);
-  } catch (error) {
+  const plugins: MarketIndexEntry[] = [...groups.entries()].map(([name, group]) => {
+    const meta = group.meta?.doc ?? group.fallback?.doc;
     return {
-      ok: false,
-      problems: [problem('not-json', `JSON 解析失败：${error instanceof Error ? error.message : String(error)}`)],
+      name,
+      versions: sortMarketVersions([...group.versions.values()]),
+      ...(meta?.title === undefined ? {} : { title: meta.title }),
+      ...(meta?.description === undefined ? {} : { description: meta.description }),
+      ...(meta?.author === undefined ? {} : { author: meta.author }),
+      ...(meta?.owner === undefined ? {} : { owner: meta.owner }),
+      ...(meta?.homepage === undefined ? {} : { homepage: meta.homepage }),
+      ...(meta?.icon === undefined ? {} : { icon: meta.icon }),
+      ...(meta?.metadata === undefined ? {} : { metadata: meta.metadata }),
     };
-  }
-}
-
-export function sortMarketVersions(versions: readonly MarketIndexVersion[]): MarketIndexVersion[] {
-  return [...versions].sort((left, right) => (compareSemver(right.version, left.version) ?? 0));
-}
-
-export function upsertMarketEntry(index: MarketIndex, entry: MarketIndexEntry): MarketIndex {
-  const found = index.plugins.findIndex((item) => item.name === entry.name);
-  if (found === -1) return { ...index, plugins: [...index.plugins, entry] };
-  const current = index.plugins[found];
-  if (current === undefined) return { ...index, plugins: [...index.plugins, entry] };
-  const merged = new Map<string, MarketIndexVersion>();
-  for (const one of current.versions) merged.set(one.version, one);
-  for (const one of entry.versions) merged.set(one.version, one);
-  const owner = current.owner ?? entry.owner;
-  const plugins = [...index.plugins];
-  plugins[found] = {
-    ...current,
-    ...entry,
-    ...(owner === undefined ? {} : { owner }),
-    versions: sortMarketVersions([...merged.values()]),
-  };
-  return { ...index, plugins };
-}
-
-export function marketEntryLabels(entry: MarketIndexEntry): readonly string[] {
-  return entry.metadata?.labels ?? [];
-}
-
-export function filterMarketIndex(index: MarketIndex, filter: DiscoverFilter): readonly MarketIndexEntry[] {
-  const query = (filter.query ?? '').trim().toLowerCase();
-  const category = (filter.category ?? '').trim();
-  const label = (filter.label ?? '').trim();
-  return index.plugins.filter((entry) => {
-    if (category !== '' && entry.metadata?.category !== category) return false;
-    if (label !== '' && !marketEntryLabels(entry).includes(label)) return false;
-    if (query === '') return true;
-    const haystack = [
-      entry.name,
-      marketText(entry.title, 'zh'),
-      marketText(entry.title, 'en'),
-      marketText(entry.description, 'zh'),
-      marketText(entry.description, 'en'),
-      entry.author ?? '',
-      ...(entry.metadata?.keywords ?? []),
-    ]
-      .join(' ')
-      .toLowerCase();
-    return haystack.includes(query);
   });
-}
-
-export function marketSourceKey(source: IndexSourceSpec): string {
-  const canonical = JSON.stringify([source.kind, source.url.trim(), source.ref ?? '', source.path ?? '']);
-  return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
-}
-
-export type SourceConfigParse =
-  | { readonly ok: true; readonly source: MarketSourceConfig }
-  | { readonly ok: false; readonly problem: MarketIndexProblem };
-
-export function parseSourceConfig(raw: unknown): SourceConfigParse {
-  const record = asRecord(raw);
-  if (record === undefined) return { ok: false, problem: problem('source', '索引源必须是对象') };
-  const id = asText(record['id']);
-  const label = asText(record['label']);
-  const kind = record['kind'];
-  const url = asText(record['url']);
-  if (id === '') return { ok: false, problem: problem('source', '索引源缺 id') };
-  if (label === '') return { ok: false, problem: problem('source', '索引源缺 label') };
-  if (kind !== 'http' && kind !== 'git') return { ok: false, problem: problem('source', 'kind 只能是 http 或 git') };
-  if (kind === 'http') {
-    const bad = httpUrlProblem(url);
-    if (bad !== undefined) return { ok: false, problem: problem('source', bad) };
-    return { ok: true, source: { id, label, kind, url } };
-  }
-  if (!gitUrlOk(url)) {
-    return { ok: false, problem: problem('source', 'git 地址不合格（只收 https / ssh / scp 形式，且不能带凭据）') };
-  }
-  const ref = asText(record['ref']);
-  const path = asText(record['path']);
-  const localPath = asText(record['localPath']);
-  const policy = record['policy'];
-  if (policy !== undefined && policy !== 'artifacts-in-repo' && policy !== 'catalog-only') {
-    return { ok: false, problem: problem('source', 'policy 只能是 artifacts-in-repo 或 catalog-only') };
+  plugins.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+  return { ok: true, index: { format: MARKET_INDEX_FORMAT, plugins } };
+}
+
+export function marketEntryFilesOf(index: MarketIndex, dir: string = MARKET_INDEX_DIR): readonly MarketEntryFile[] {
+  const files: MarketEntryFile[] = [];
+  for (const entry of index.plugins) {
+    for (const version of entry.versions) {
+      files.push({
+        path: marketEntryPath(dir, entry.name, version.version),
+        text: `${JSON.stringify(marketVersionDocOf(entry, version), null, 2)}\n`,
+      });
+    }
   }
-  return {
-    ok: true,
-    source: {
-      id,
-      label,
-      kind,
-      url,
-      ...(ref === '' ? {} : { ref }),
-      ...(path === '' ? {} : { path }),
-      ...(localPath === '' ? {} : { localPath }),
-      ...(policy === undefined ? {} : { policy: policy as MarketSourceConfig['policy'] }),
-    },
+  return files;
+}
+
+export function collectMarketEntryFiles(dir: string): readonly MarketEntryFile[] {
+  if (!existsSync(dir)) return [];
+  const files: MarketEntryFile[] = [];
+  const walk = (current: string): void => {
+    for (const item of readdirSync(current, { withFileTypes: true })) {
+      const full = join(current, item.name);
+      if (item.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (!item.name.endsWith('.json')) continue;
+      files.push({ path: relative(dir, full).split(sep).join('/'), text: readFileSync(full, 'utf8') });
+    }
   };
+  walk(dir);
+  return files;
 }
 
-export function httpUrlProblem(url: string): string | undefined {
-  let parsed: URL;
-  try {
-    parsed = new URL(url);
-  } catch {
-    return '不是合法 URL';
-  }
-  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return '只收 http / https';
-  if (parsed.username !== '' || parsed.password !== '') return 'URL 不能带凭据';
-  if (parsed.search !== '' || parsed.hash !== '') return 'URL 不能带 query / fragment';
-  return undefined;
-}
-
-export function gitUrlOk(url: string): boolean {
-  if (url === '') return false;
-  if (/^[^@\s]+@[^@\s:]+:[^@\s]+$/.test(url)) return true;
-  let parsed: URL;
-  try {
-    parsed = new URL(url);
-  } catch {
-    return false;
-  }
-  if (parsed.protocol !== 'https:' && parsed.protocol !== 'ssh:' && parsed.protocol !== 'http:') return false;
-  if (parsed.password !== '') return false;
-  if (parsed.username !== '' && parsed.protocol !== 'ssh:') return false;
-  if (parsed.search !== '' || parsed.hash !== '') return false;
-  return true;
+export function marketEntryFilesOfLegacy(text: string, dir: string = MARKET_INDEX_DIR): readonly MarketEntryFile[] | undefined {
+  const parsed = parseMarketIndexJson(text);
+  if (!parsed.ok) return undefined;
+  return marketEntryFilesOf(parsed.index, dir);
 }

package/src/host/opencli-runner.ts

@@ -0,0 +1,76 @@
+import type { DataError, DataRequest, DataResult } from '../contract/data.js';
+
+/**
+ * 一条 opencli 命令的执行器：同一形状的 `execFile('opencli', args)`，结果只留 stdout。
+ */
+export type OpencliRunner = (
+  args: readonly string[],
+) => Promise<{ readonly stdout: string }>;
+
+/**
+ * 读缝（`DataReader.read`）的形状；模块直接把自己的 `data.read` 传进来即可。
+ */
+export type OpencliRead = (
+  request: DataRequest,
+) => Promise<DataResult<unknown>>;
+
+export interface OpencliRunnerOptions {
+  readonly timeoutMs?: number;
+}
+
+const AUTH_REQUIRED_EXIT_CODE = 77;
+
+function textOf(value: unknown): string {
+  return typeof value === 'string' ? value : '';
+}
+
+function failedOf(args: readonly string[], error: DataError | undefined): Error {
+  const head = `Command failed: opencli ${args.join(' ')}`;
+  const auth = error?.pageCode === 'auth-required';
+  const helpUrl = textOf(error?.helpUrl);
+  const detail = textOf(error?.detail);
+  const hint = textOf(error?.hint);
+  const failed = new Error(
+    [
+      head,
+      ...(auth
+        ? ['code: AUTH_REQUIRED', `message: ${textOf(error?.message)}`]
+        : [textOf(error?.message) || 'opencli 这条命令没跑通']),
+      ...(detail === '' ? [] : [detail]),
+      ...(hint === '' ? [] : [hint]),
+      ...(auth && helpUrl !== ''
+        ? [`help: Please open Chrome or Chromium and log in to ${helpUrl}`]
+        : []),
+    ].join('\n'),
+  );
+  if (auth) (failed as Error & { code?: number }).code = AUTH_REQUIRED_EXIT_CODE;
+  return failed;
+}
+
+/**
+ * 把读缝包成一条 opencli 命令的执行器：给还按 `execFile('opencli', args)` 收结果的编排库用，
+ * 让它们跑在面板用的那份 opencli 上（同一套插件、同一份登录态）。
+ *
+ * 失败按 opencli 自己的约定还原：未登录是 `code: AUTH_REQUIRED` + 退出码 77，编排库的
+ * 「等登录再重试」才接得上；其它失败保留 `Command failed: opencli …` 那句外壳。
+ * @param read 模块手里的读缝（`data.read`）。
+ * @param options `timeoutMs` 透传给读缝；不传就用读缝自己的默认值。
+ * @returns 执行器；直接交给编排库的 `setOpencliRunner`。
+ */
+export function opencliRunnerOf(
+  read: OpencliRead,
+  options: OpencliRunnerOptions = {},
+): OpencliRunner {
+  return async (args) => {
+    const result = await read({
+      kind: 'command',
+      adapter: 'opencli',
+      argv: [...args],
+      ...(options.timeoutMs === undefined
+        ? {}
+        : { timeoutMs: options.timeoutMs }),
+    });
+    if (result.ok) return { stdout: JSON.stringify(result.data) };
+    throw failedOf(args, result.error);
+  };
+}

package/src/host.ts

@@ -34,6 +34,8 @@ export * from './host/tokens.js';
 export * from './host/tool-approval.js';
 export * from './host/tool-kit.js';
 export * from './host/unit-face.js';
+export * from './host/opencli-runner.js';
+export * from './host/lib-runners.js';
 export * from './host/value-handoff.js';
 export * from './host/workspace-store.js';
 export * from './host/write-result.js';