@dsh-workbench/shared 1.1.7 → 1.1.9

package/src/host/installed-module.ts

@@ -0,0 +1,272 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { DshHostContext } from '../api/dsh.js';
+import { declarationProblemsOf, readDeclaration } from '../contract/unit-declaration.js';
+import { packageSourceOf } from './installed-sources.js';
+import { scopeOf } from './adapter-types.js';
+import { isPackageName } from './spec.js';
+import type { InstalledModule, ProfileModule, ProfilePackage } from './adapter-types.js';
+export interface UnitDeclarationSource {
+  readonly pkg: string;
+  readonly declaration: unknown;
+}
+
+function asRecord(value: unknown): Readonly<Record<string, unknown>> | undefined {
+  return typeof value === 'object' && value !== null ? (value as Readonly<Record<string, unknown>>) : undefined;
+}
+
+function asText(value: unknown): string {
+  return typeof value === 'string' ? value : '';
+}
+
+export function profileDirOf(ctx: DshHostContext): string | null {
+  const profile = ctx.get<{ dir?: unknown }>('profileContext');
+  const dir = typeof profile?.dir === 'string' ? profile.dir.trim() : '';
+  return dir === '' ? null : dir;
+}
+
+function stringsOf(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : [];
+}
+
+export function profileManifestOf(profileDir: string | null): Readonly<Record<string, unknown>> | undefined {
+  if (profileDir === null) return undefined;
+  try {
+    return asRecord(JSON.parse(fs.readFileSync(path.join(profileDir, 'package.json'), 'utf8')));
+  } catch {
+    return undefined;
+  }
+}
+
+export function profileModules(profileDir: string | null): readonly ProfileModule[] {
+  const record = profileManifestOf(profileDir);
+  if (record === undefined) return [];
+  const bundles = stringsOf(asRecord(asRecord(record.dsh)?.profile)?.bundles);
+  const dependencies = asRecord(record.dependencies) ?? {};
+  const names = bundles.length > 0 ? bundles : Object.keys(dependencies);
+  const found: ProfileModule[] = [];
+  for (const pkg of names) {
+    const read = readInstalledModule(profileDir, pkg);
+    if (read.kind === 'module') {
+      const spec = asText(dependencies[read.pkg]);
+      found.push({
+        pkg: read.pkg,
+        unit: read.unit,
+        version: read.version,
+        ...(read.registry === undefined ? {} : { registry: read.registry }),
+        local: isLocalDependencySpec(spec),
+        fromRegistry: isRegistryDependencySpec(spec),
+      });
+    }
+  }
+  return found;
+}
+
+export function createDeclarationLookup(
+  profileDir: string | null,
+): (unit: string) => UnitDeclarationSource | undefined {
+  let roster: Map<string, string> | undefined;
+  const scan = (): Map<string, string> =>
+    new Map(profileModules(profileDir).map((row) => [row.unit, row.pkg]));
+  return (unit) => {
+    roster ??= scan();
+    let pkg = roster.get(unit);
+    if (pkg === undefined) {
+      roster = scan();
+      pkg = roster.get(unit);
+    }
+    return pkg === undefined ? undefined : { pkg, declaration: moduleDeclarationOf(profileDir, pkg) };
+  };
+}
+
+function registryFromLockfile(profileDir: string, pkg: string): string | undefined {
+  let text: string;
+  try {
+    text = fs.readFileSync(path.join(profileDir, 'pnpm-lock.yaml'), 'utf8');
+  } catch {
+    return undefined;
+  }
+  const at = text.indexOf(`  ${pkg}@`);
+  const quoted = at === -1 ? text.indexOf(`  '${pkg}@`) : at;
+  if (quoted === -1) return undefined;
+  const headerEnd = text.indexOf('\n', quoted);
+  const end = headerEnd === -1 ? -1 : text.indexOf('\n  ', headerEnd + 1);
+  const block = text.slice(quoted, end === -1 ? quoted + 900 : end);
+  const match = /tarball:\s*([^\s,}]+)/.exec(block);
+  const tarball = match?.[1];
+  if (tarball === undefined || !tarball.startsWith('http')) return undefined;
+  const cut = tarball.lastIndexOf(`/${pkg}/`);
+  if (cut <= 'https://'.length) return undefined;
+  return tarball.slice(0, cut);
+}
+
+function unquoted(value: string): string {
+  const quote = value.charAt(0);
+  if (value.length >= 2 && (quote === '"' || quote === "'") && value.endsWith(quote)) {
+    return value.slice(1, -1).trim();
+  }
+  return value;
+}
+
+function registryFromNpmrc(profileDir: string, pkg: string): string | undefined {
+  let text: string;
+  try {
+    text = fs.readFileSync(path.join(profileDir, '.npmrc'), 'utf8');
+  } catch {
+    return undefined;
+  }
+  const scope = scopeOf(pkg);
+  let fallback: string | undefined;
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('#') || trimmed.startsWith(';')) continue;
+    const separator = trimmed.indexOf('=');
+    if (separator <= 0) continue;
+    const key = trimmed.slice(0, separator).trim();
+    const value = unquoted(trimmed.slice(separator + 1).trim());
+    if (value === '') continue;
+    if (scope !== null && key === `${scope}:registry`) return value;
+    if (key === 'registry') fallback = value;
+  }
+  return fallback;
+}
+
+function registryOf(
+  profileDir: string,
+  pkg: string,
+  manifest: Readonly<Record<string, unknown>>,
+): string | undefined {
+  const declared = asText(asRecord(manifest.publishConfig)?.registry);
+  if (declared !== '') return declared;
+  const recorded = packageSourceOf(profileDir, pkg);
+  if (recorded !== undefined) return recorded.registry;
+  const locked = registryFromLockfile(profileDir, pkg);
+  return locked === undefined ? registryFromNpmrc(profileDir, pkg) : locked;
+}
+
+export function moduleDeclarationOf(profileDir: string | null, pkg: string): unknown {
+  if (profileDir === null || !isPackageName(pkg)) return undefined;
+  try {
+    const text = fs.readFileSync(path.join(profileDir, 'node_modules', pkg, 'package.json'), 'utf8');
+    return asRecord(asRecord(asRecord(JSON.parse(text))?.dsh)?.workbench);
+  } catch {
+    return undefined;
+  }
+}
+
+export interface DeclarationGap {
+  readonly pkg: string;
+  readonly problems: readonly string[];
+}
+
+export function declarationGaps(profileDir: string | null): readonly DeclarationGap[] | undefined {
+  if (profileManifestOf(profileDir) === undefined) return undefined;
+  const gaps: DeclarationGap[] = [];
+  for (const module of profileModules(profileDir)) {
+    const problems = declarationProblemsOf(module.pkg, moduleDeclarationOf(profileDir, module.pkg));
+    if (problems.length > 0) gaps.push({ pkg: module.pkg, problems });
+  }
+  return gaps;
+}
+
+export function declaredPluginCommands(profileDir: string | null): ReadonlyMap<string, ReadonlySet<string>> {
+  const declared = new Map<string, Set<string>>();
+  for (const module of profileModules(profileDir)) {
+    const read = readDeclaration(module.pkg, moduleDeclarationOf(profileDir, module.pkg));
+    for (const need of read.manifest?.needs ?? []) {
+      if (need.kind !== 'extension') continue;
+      const name = need.name.trim();
+      if (name === '') continue;
+      const commands = declared.get(name) ?? new Set<string>();
+      for (const command of need.commands ?? []) commands.add(command);
+      declared.set(name, commands);
+    }
+  }
+  return declared;
+}
+
+export function readInstalledModule(profileDir: string | null, pkg: string): InstalledModule {
+  if (profileDir === null || !isPackageName(pkg)) return { kind: 'unknown', pkg };
+  let manifest: unknown;
+  try {
+    manifest = JSON.parse(fs.readFileSync(path.join(profileDir, 'node_modules', pkg, 'package.json'), 'utf8'));
+  } catch {
+    return { kind: 'unknown', pkg };
+  }
+  const record = asRecord(manifest);
+  if (record === undefined) return { kind: 'unknown', pkg };
+  const declared = asRecord(asRecord(record.dsh)?.workbench);
+  const unit = declared === undefined ? '' : asText(declared.unit);
+  if (unit === '') return { kind: 'not-module', pkg };
+  const registry = registryOf(profileDir, pkg, record);
+  return {
+    kind: 'module',
+    pkg,
+    unit,
+    version: asText(record.version),
+    ...(registry === undefined ? {} : { registry }),
+  };
+}
+
+const PACKED_ARTIFACT = /\.(?:tgz|tar\.gz|tar)$/i;
+
+export function isPackedArtifactSpec(spec: string): boolean {
+  const trimmed = spec.trim();
+  const pkgPath = trimmed.startsWith('file:') ? trimmed.slice('file:'.length) : trimmed;
+  return PACKED_ARTIFACT.test(pkgPath);
+}
+
+export function isLocalDependencySpec(spec: string): boolean {
+  const trimmed = spec.trim();
+  if (isPackedArtifactSpec(trimmed)) return false;
+  return (
+    trimmed.startsWith('link:') ||
+    trimmed.startsWith('file:') ||
+    trimmed.startsWith('./') ||
+    trimmed.startsWith('../') ||
+    trimmed.startsWith('/')
+  );
+}
+
+const NON_REGISTRY_SPEC = /^(?:git\+|git:|github:|gitlab:|bitbucket:|https?:|ssh:|workspace:)/i;
+
+export function isRegistryDependencySpec(spec: string): boolean {
+  const trimmed = spec.trim();
+  if (trimmed === '') return true;
+  if (isLocalDependencySpec(trimmed) || isPackedArtifactSpec(trimmed)) return false;
+  return !NON_REGISTRY_SPEC.test(trimmed);
+}
+
+export function readProfilePackage(profileDir: string | null, pkg: string): ProfilePackage | undefined {
+  if (profileDir === null || !isPackageName(pkg)) return undefined;
+  let manifest: unknown;
+  try {
+    manifest = JSON.parse(fs.readFileSync(path.join(profileDir, 'node_modules', pkg, 'package.json'), 'utf8'));
+  } catch {
+    return undefined;
+  }
+  const record = asRecord(manifest);
+  if (record === undefined) return undefined;
+  const version = asText(record.version);
+  if (version === '') return undefined;
+  const registry = registryOf(profileDir, pkg, record);
+  const dependencies = asRecord(profileManifestOf(profileDir)?.dependencies) ?? {};
+  const local = isLocalDependencySpec(asText(dependencies[pkg]));
+  return {
+    pkg,
+    version,
+    ...(registry === undefined ? {} : { registry }),
+    ...(local ? { local: true } : {}),
+  };
+}
+
+export function packageVersionAt(packageRoot: string): string | undefined {
+  let manifest: unknown;
+  try {
+    manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+  } catch {
+    return undefined;
+  }
+  const version = asText(asRecord(manifest)?.version);
+  return version === '' ? undefined : version;
+}

package/src/host/lib-install.ts

@@ -1,8 +1,7 @@
 import type { BinNeed, LibNeed, SupplySource } from '../contract/needs.js';
 import type { HostOs } from '../contract/protocol/platform.js';
-import { npmRegistryOf } from './plugin-source.js';
+import { npmRegistryOf } from './npm-registry.js';
 import { quoteShellArg } from './shell-text.js';
-import { libsPrefix, npmCacheDir } from './paths.js';
 
 export type NpmSource = Extract<SupplySource, { kind: 'npm' }>;
 
@@ -11,26 +10,23 @@ export function libInstallCommand(options: {
   readonly source: NpmSource;
   readonly version?: string | undefined;
   readonly env?: NodeJS.ProcessEnv | undefined;
+  readonly prefix: string;
+  readonly cacheDir?: string | undefined;
 }): string {
   const { need, source, version } = options;
   const registry = npmRegistryOf(source, options.env ?? process.env);
   const spec = version ?? need.version ?? 'latest';
   const registryFlag = registry.ok ? ` --registry ${quoteShellArg(registry.value)}` : '';
-  return `npm i --prefix ${quoteShellArg(libsPrefix())} ${quoteShellArg(`${need.name}@${spec}`)}${registryFlag} --cache ${quoteShellArg(npmCacheDir())}`;
+  const cacheFlag = options.cacheDir === undefined ? '' : ` --cache ${quoteShellArg(options.cacheDir)}`;
+  return `npm i --prefix ${quoteShellArg(options.prefix)} ${quoteShellArg(`${need.name}@${spec}`)}${registryFlag}${cacheFlag}`;
 }
 
-/**
- * 这个 bin 在这台机器上怎么装：作者写了 `install` 且平台对得上才给出那条命令。
- * `command` 原样照抄；`npm` 装进隔离运行时的共用依赖前缀（那份包里的 bin 会自动上 PATH）。
- * @param need 一条 bin 需要。
- * @param os 宿主平台（由平台适配器给出）。
- * @param env 取 registry 环境变量的地方。
- * @returns 一条能直接粘进终端的命令；没声明或平台不对就是 undefined。
- */
 export function binInstallCommand(
   need: BinNeed,
   os: HostOs,
-  env: NodeJS.ProcessEnv = process.env,
+  env: NodeJS.ProcessEnv,
+  prefix: string,
+  cacheDir?: string,
 ): string | undefined {
   const install = need.install;
   if (install === undefined) return undefined;
@@ -42,6 +38,8 @@ export function binInstallCommand(
   const packageName = install.package.trim();
   if (packageName === '') return undefined;
   return libInstallCommand({
+    prefix,
+    ...(cacheDir === undefined ? {} : { cacheDir }),
     need: { kind: 'lib', name: packageName, purpose: need.purpose },
     source: {
       kind: 'npm',
@@ -52,3 +50,7 @@ export function binInstallCommand(
     env,
   });
 }
+
+export function libUninstallCommand(options: { readonly need: LibNeed; readonly prefix: string }): string {
+  return `npm uninstall --prefix ${quoteShellArg(options.prefix)} ${quoteShellArg(options.need.name)}`;
+}

package/src/host/lib-runners.ts

@@ -1,17 +1,15 @@
 import type { LibNeed } from '../contract/needs.js';
 import type { LibReader } from '../contract/lib.js';
-import type { OpencliRunner } from './opencli-runner.js';
+import type { LibRunner } from '../contract/runner.js';
 
-export interface LibRuntimes {
-  readonly opencli?: OpencliRunner | undefined;
-}
+export type LibRuntimes = Readonly<Record<string, LibRunner>>;
 
 interface Logger {
   warn?(message: string): void;
 }
 
-function runnerOf(runtimes: LibRuntimes, runtime: string): OpencliRunner | undefined {
-  return runtime === 'opencli' ? runtimes.opencli : undefined;
+function runnerOf(runtimes: LibRuntimes, runtime: string): LibRunner | undefined {
+  return runtimes[runtime];
 }
 
 function setterNameOf(runtime: string): string {
@@ -19,7 +17,7 @@ function setterNameOf(runtime: string): string {
 }
 
 /**
- * 给声明了 `runs` 的 lib 注入「跑这个运行时」的执行器：库侧按约定暴露 `setOpencliRunner`
+ * 给声明了 `runs` 的 lib 注入「跑这个运行时」的执行器：库侧按约定暴露 `set<Runtime>Runner`
  * （运行时名字首字母大写 + `Runner`），外壳在每次 `load` 之后把执行器交给它。
  *
  * 没暴露的（版本旧）就保持它自己的行为（按 PATH 找），只记一条 warn；不熟悉的运行时同样只 warn。
@@ -62,7 +60,7 @@ export function withLibRunners(
           );
           continue;
         }
-        (setter as (runner: OpencliRunner) => void).call(module, runner);
+        (setter as (runner: LibRunner) => void).call(module, runner);
       }
       return module;
     },

package/src/host/local-declaration.ts

@@ -0,0 +1,37 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { localDirOf } from './spec.js';
+export { localDirOf };
+import { declarationProblemsOf } from '../contract/unit-declaration.js';
+
+function asRecord(value: unknown): Readonly<Record<string, unknown>> | undefined {
+  return typeof value === 'object' && value !== null ? (value as Readonly<Record<string, unknown>>) : undefined;
+}
+
+export function packageManifestOf(dir: string): Readonly<Record<string, unknown>> | undefined {
+  try {
+    const parsed: unknown = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    return asRecord(parsed);
+  } catch {
+    return undefined;
+  }
+}
+
+export function dshRecordOf(dir: string): unknown | undefined {
+  return packageManifestOf(dir)?.dsh;
+}
+
+export function packageNameOf(dir: string): string | undefined {
+  const name = packageManifestOf(dir)?.name;
+  return typeof name === 'string' && name.trim() !== '' ? name.trim() : undefined;
+}
+
+export function pathDeclarationOf(spec: string): unknown | undefined {
+  const dir = localDirOf(spec);
+  return dir === undefined ? undefined : asRecord(dshRecordOf(dir))?.workbench;
+}
+
+export function declarationRefusalOf(name: string, raw: unknown): readonly string[] {
+  if (raw === undefined) return [];
+  return declarationProblemsOf(name, raw);
+}

package/src/host/market-index-claim.ts

@@ -58,10 +58,6 @@ export function marketArtifactRoot(name: string): string {
   return `${MARKET_ARTIFACTS_DIR}/${name}`;
 }
 
-export function marketArtifactPathFor(name: string, version: string): string {
-  return `${MARKET_ARTIFACTS_DIR}/${name}/${version}`;
-}
-
 export function entryUnitOf(entry: MarketIndexEntry): string | undefined {
   const unit = entry.metadata?.unit?.trim();
   if (unit !== undefined && unit !== '') return unit;

package/src/host/market-index-doc.ts

@@ -1,45 +1,4 @@
-import type {
-  MarketIndex,
-  MarketIndexEngines,
-  MarketIndexEntryMetadata,
-  MarketIndexProblem,
-  MarketIndexSource,
-  MarketLocalizedText,
-} from '../contract/protocol/market-index.js';
-
-export interface MarketVersionDoc {
-  readonly name: string;
-  readonly version: string;
-  readonly source: MarketIndexSource;
-  readonly publishTimestamp?: number;
-  readonly engines?: MarketIndexEngines;
-  readonly title?: MarketLocalizedText;
-  readonly description?: MarketLocalizedText;
-  readonly author?: string;
-  readonly owner?: string;
-  readonly homepage?: string;
-  readonly icon?: string;
-  readonly metadata?: MarketIndexEntryMetadata;
-}
-
-export interface MarketMetaDoc {
-  readonly name: string;
-  readonly epoch?: number;
-  readonly publishTimestamp: number;
-  readonly title?: MarketLocalizedText;
-  readonly description?: MarketLocalizedText;
-  readonly author?: string;
-  readonly owner?: string;
-  readonly homepage?: string;
-  readonly icon?: string;
-  readonly metadata?: MarketIndexEntryMetadata;
-}
-
-export type MarketEntryDoc = MarketVersionDoc | MarketMetaDoc;
-
-export type MarketEntryDocParse =
-  | { readonly ok: true; readonly doc: MarketEntryDoc }
-  | { readonly ok: false; readonly problems: readonly MarketIndexProblem[] };
+import type { MarketIndex, MarketIndexProblem } from '../contract/protocol/market-index.js';
 
 export interface MarketEntryFile {
   readonly path: string;
@@ -49,14 +8,3 @@ export interface MarketEntryFile {
 export type MarketIndexAssemble =
   | { readonly ok: true; readonly index: MarketIndex }
   | { readonly ok: false; readonly problems: readonly MarketIndexProblem[] };
-
-export interface MarketDocFields {
-  readonly name: string;
-  readonly title?: MarketLocalizedText;
-  readonly description?: MarketLocalizedText;
-  readonly author?: string;
-  readonly owner?: string;
-  readonly homepage?: string;
-  readonly icon?: string;
-  readonly metadata?: MarketIndexEntryMetadata;
-}

package/src/host/market-index-parse.ts

@@ -13,7 +13,6 @@ import type {
 } from '../contract/protocol/market-index.js';
 import { MARKET_INDEX_DIR, MARKET_INDEX_FORMAT } from '../contract/protocol/market-index.js';
 import { marketText } from '../lib/market-index.js';
-import type { MarketDocFields, MarketEntryDocParse } from './market-index-doc.js';
 import { compareVersions, isValidVersion } from './version.js';
 
 const NPM_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
@@ -388,95 +387,32 @@ export function parseSourceConfig(raw: unknown): SourceConfigParse {
 }
 
 
-function docFieldsOf(record: Readonly<Record<string, unknown>>, at: string): MarketDocFields | MarketIndexProblem {
-  const name = asText(record['name']);
-  if (name === '' || name.length > 214 || !NPM_NAME.test(name)) {
-    return problem('name', `不是合法 npm 包名：${JSON.stringify(name)}`, at);
-  }
-  const icon = asText(record['icon']);
-  if (icon !== '') {
-    const badIcon = iconProblem(icon);
-    if (badIcon !== undefined) return badIcon;
-  }
-  const owner = asText(record['owner']);
-  if (owner !== '') {
-    const badOwner = ownerProblem(owner);
-    if (badOwner !== undefined) return badOwner;
-  }
-  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);
-  }
-  const title = asLocalized(record['title']);
-  const description = asLocalized(record['description']);
-  const author = asText(record['author']);
-  const homepage = asText(record['homepage']);
-  return {
-    name,
-    ...(title === undefined ? {} : { title }),
-    ...(description === undefined ? {} : { description }),
-    ...(author === '' ? {} : { author }),
-    ...(owner === '' ? {} : { owner }),
-    ...(homepage === '' ? {} : { homepage }),
-    ...(icon === '' ? {} : { icon }),
-    ...(metadata === undefined ? {} : { metadata }),
-  };
-}
-
-export function parseMarketEntryDoc(raw: unknown): MarketEntryDocParse {
-  const record = asRecord(raw);
-  if (record === undefined) return { ok: false, problems: [problem('entry', '条目文件必须是一个 JSON 对象')] };
-  const fields = docFieldsOf(record, 'entry');
-  if ('kind' in fields) return { ok: false, problems: [fields] };
-  const version = asText(record['version']);
-  const timestamp = record['publishTimestamp'];
-  if (timestamp !== undefined && (!Number.isInteger(timestamp) || (timestamp as number) < 0)) {
-    return { ok: false, problems: [problem('timestamp', 'publishTimestamp 必须是 Unix 秒整数', 'entry')] };
-  }
-  if (version === '') {
-    if (timestamp === undefined) {
-      return { ok: false, problems: [problem('timestamp', '元数据文件要有 publishTimestamp', 'entry')] };
-    }
-    const epoch = record['epoch'];
-    if (epoch !== undefined && (!Number.isInteger(epoch) || (epoch as number) < 0)) {
-      return { ok: false, problems: [problem('timestamp', 'epoch 必须是非负整数', 'entry')] };
-    }
-    return {
-      ok: true,
-      doc: { ...fields, publishTimestamp: timestamp as number, ...(epoch === undefined ? {} : { epoch: epoch as number }) },
-    };
-  }
-  if (!isValidVersion(version)) {
-    return { ok: false, problems: [problem('version', `版本号不是合法 SemVer：${JSON.stringify(version)}`, 'entry')] };
-  }
-  const source = sourceOf(record['source'], 'entry.source');
-  if ('kind' in source) return { ok: false, problems: [source] };
-  const engines = asRecord(record['engines']);
-  const dsh = engines === undefined ? '' : asText(engines['dsh']);
-  return {
-    ok: true,
-    doc: {
-      ...fields,
-      version,
-      source,
-      ...(timestamp === undefined ? {} : { publishTimestamp: timestamp as number }),
-      ...(dsh === '' ? {} : { engines: { dsh } }),
-    },
-  };
-}
 function indexPathBase(dir: string): string {
   return dir.replace(/^\/+|\/+$/g, '') || MARKET_INDEX_DIR;
 }
 
-export function marketEntryPath(dir: string, name: string, version: string): string {
+export function marketEntryPath(dir: string, name: string): string {
   if (!NPM_NAME.test(name)) throw new Error(`不是合法包名：${JSON.stringify(name)}`);
-  if (!isValidVersion(version)) throw new Error(`不是合法版本号：${JSON.stringify(version)}`);
-  return `${indexPathBase(dir)}/${name}/${version}.json`;
+  return `${indexPathBase(dir)}/${name}.json`;
 }
 
-export function marketMetaPath(dir: string, name: string, epoch: number, suffix: string): string {
-  if (!NPM_NAME.test(name)) throw new Error(`不是合法包名：${JSON.stringify(name)}`);
-  if (!Number.isInteger(epoch) || epoch < 0) throw new Error(`epoch 不合法：${String(epoch)}`);
-  if (!/^[a-z0-9]{4,16}$/u.test(suffix)) throw new Error(`后缀不合法：${suffix}`);
-  return `${indexPathBase(dir)}/${name}/meta-${String(epoch)}-${suffix}.json`;
+export type MarketEntryParse =
+  | { readonly ok: true; readonly entry: MarketIndexEntry }
+  | { readonly ok: false; readonly problems: readonly MarketIndexProblem[] };
+
+export function parseMarketEntryJson(text: string): MarketEntryParse {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (error) {
+    return {
+      ok: false,
+      problems: [problem('not-json', `JSON 解析失败：${error instanceof Error ? error.message : String(error)}`, 'entry')],
+    };
+  }
+  const parsed = entryOf(raw, 'entry');
+  if ('kind' in parsed) return { ok: false, problems: [parsed] };
+  return { ok: true, entry: parsed };
 }
+
+