@dsh-workbench/shared 1.1.8 → 1.1.10

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/module-root.ts

@@ -0,0 +1,6 @@
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function packageRootOf(moduleUrl: string): string {
+  return dirname(dirname(dirname(fileURLToPath(moduleUrl))));
+}

package/src/host/npm-registry.ts

@@ -0,0 +1,21 @@
+function envValue(
+  env: Readonly<Record<string, string | undefined>>,
+  name: string,
+): { readonly ok: true; readonly value: string } | { readonly ok: false } {
+  const value = env[name]?.trim();
+  return value === undefined || value === '' ? { ok: false } : { ok: true, value };
+}
+
+export function npmRegistryOf(
+  source: { readonly registryEnv?: string; readonly registryDefault?: string },
+  env: Readonly<Record<string, string | undefined>>,
+): { readonly ok: true; readonly value: string } | { readonly ok: false; readonly env: string } {
+  const name = source.registryEnv ?? '';
+  if (name !== '') {
+    const fromEnv = envValue(env, name);
+    if (fromEnv.ok) return fromEnv;
+  }
+  const fallback = source.registryDefault?.trim();
+  if (fallback === undefined || fallback === '') return { ok: false, env: name };
+  return { ok: true, value: fallback };
+}

package/src/host/package-content.ts

@@ -0,0 +1,76 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import type { DshShell } from '../api/dsh.js';
+import { INSTALL_TIMEOUT_MS } from '../config/constants.js';
+import { parseJsonLoose } from '../lib/text.js';
+import { quoteShellArg } from './shell-text.js';
+import { runShell } from './shell.js';
+import { splitNpmSpec } from './package-kind.js';
+import { localDirOf } from './local-declaration.js';
+
+function cacheFlag(cacheDir: string | undefined): string {
+  return cacheDir === undefined ? '' : ` --cache ${quoteShellArg(cacheDir)}`;
+}
+
+function packedFileFrom(stdout: string, root: string): string | undefined {
+  const parsed = parseJsonLoose(stdout);
+  if (Array.isArray(parsed)) {
+    const first: unknown = parsed[0];
+    const filename =
+      typeof first === 'object' && first !== null ? (first as { filename?: unknown }).filename : undefined;
+    if (typeof filename === 'string' && filename.trim() !== '') {
+      const at = path.join(root, path.basename(filename.trim()));
+      if (fs.existsSync(at)) return at;
+    }
+  }
+  try {
+    const found = fs.readdirSync(root).filter((name) => name.endsWith('.tgz'));
+    return found.length === 1 ? path.join(root, found[0] ?? '') : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function withPackageDir<T>(
+  options: {
+    readonly shell?: DshShell | undefined;
+    readonly spec: string;
+    readonly registry?: string | undefined;
+    readonly cacheDir?: string | undefined;
+  },
+  visit: (dir: string) => T,
+): Promise<T | undefined> {
+  const local = localDirOf(options.spec);
+  if (local !== undefined) return visit(local);
+  if (splitNpmSpec(options.spec) === undefined) return undefined;
+  const shell = options.shell;
+  if (shell === undefined) return undefined;
+
+  let root: string;
+  try {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'wb-package-'));
+  } catch {
+    return undefined;
+  }
+  try {
+    const at = options.registry === undefined ? '' : ` --registry ${quoteShellArg(options.registry)}`;
+    const packed = await runShell(
+      shell,
+      `npm pack ${quoteShellArg(options.spec)} --ignore-scripts --json --pack-destination ${quoteShellArg(root)}${cacheFlag(options.cacheDir)}${at}`,
+      { timeoutMs: INSTALL_TIMEOUT_MS },
+    ).catch(() => undefined);
+    if (packed === undefined || packed.exitCode !== 0) return undefined;
+    const file = packedFileFrom(packed.stdout, root);
+    if (file === undefined) return undefined;
+    const unpacked = await runShell(shell, `tar -xzf ${quoteShellArg(file)} -C ${quoteShellArg(root)}`, {
+      timeoutMs: INSTALL_TIMEOUT_MS,
+    }).catch(() => undefined);
+    if (unpacked === undefined || unpacked.exitCode !== 0) return undefined;
+    const dir = path.join(root, 'package');
+    if (!fs.existsSync(dir)) return undefined;
+    return visit(dir);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}

package/src/host/package-kind.ts

@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export { splitNpmSpec } from './spec.js';
+export type { NpmRef } from './spec.js';
+import { dshRecordOf, packageManifestOf, packageNameOf } from './local-declaration.js';
+import { pluginAt } from './plugin.js';
+
+export type PackageKind = 'runtime-plugin' | 'dsh-bundle' | 'both' | 'neither';
+
+export interface PackageVerdict {
+  readonly kind: PackageKind;
+  readonly pkg?: string;
+  readonly pluginName?: string;
+}
+
+function asRecord(value: unknown): Readonly<Record<string, unknown>> | undefined {
+  return typeof value === 'object' && value !== null ? (value as Readonly<Record<string, unknown>>) : undefined;
+}
+
+export function isCommandFile(name: string): boolean {
+  if (name.endsWith('.d.ts') || name.endsWith('.test.ts')) return false;
+  if (name.endsWith('.d.js')) return false;
+  return name.endsWith('.ts') || name.endsWith('.js');
+}
+
+export function pluginManifestOf(dir: string, manifestFile: string): Readonly<Record<string, unknown>> | undefined {
+  try {
+    const parsed: unknown = JSON.parse(fs.readFileSync(path.join(dir, manifestFile), 'utf8'));
+    if (Array.isArray(parsed)) return undefined;
+    return asRecord(parsed);
+  } catch {
+    return undefined;
+  }
+}
+
+export function hasCommandFile(dir: string): boolean {
+  try {
+    return fs.readdirSync(dir).some(isCommandFile);
+  } catch {
+    return false;
+  }
+}
+
+export function dshMarkersOf(raw: unknown): boolean {
+  const record = asRecord(raw);
+  return record !== undefined && ('bundle' in record || 'workbench' in record);
+}
+
+export function verdictOf(dir: string, manifestFile: string): PackageVerdict | undefined {
+  const plugin = pluginAt(dir, manifestFile);
+  if (packageManifestOf(dir) === undefined && plugin === undefined) return undefined;
+  const dsh = dshMarkersOf(dshRecordOf(dir));
+  const kind: PackageKind =
+    plugin !== undefined && dsh ? 'both' : plugin !== undefined ? 'runtime-plugin' : dsh ? 'dsh-bundle' : 'neither';
+  const pkg = packageNameOf(dir);
+  return {
+    kind,
+    ...(pkg === undefined ? {} : { pkg }),
+    ...(plugin?.name === undefined ? {} : { pluginName: plugin.name }),
+  };
+}
+
+

package/src/host/package-route.ts

@@ -0,0 +1,93 @@
+import type { DshShell } from '../api/dsh.js';
+import { VERSION_CHECK_TTL_MS } from '../config/constants.js';
+import { dshMarkersOf, splitNpmSpec, verdictOf, type PackageVerdict } from './package-kind.js';
+import { withPackageDir } from './package-content.js';
+import { localDirOf } from './local-declaration.js';
+
+export type PackageRouteKind = 'runtime-plugin' | 'dsh-bundle' | 'neither';
+
+export interface PackageRoute {
+  readonly kind: PackageRouteKind;
+  readonly pkg?: string;
+  readonly pluginName?: string;
+}
+
+function routeOfVerdict(verdict: PackageVerdict, fallback?: string): PackageRoute {
+  const pkg = verdict.pkg ?? fallback;
+  if (verdict.kind === 'neither') return { kind: 'neither', ...(pkg === undefined ? {} : { pkg }) };
+  if (verdict.kind === 'dsh-bundle' || verdict.kind === 'both') return { kind: 'dsh-bundle' };
+  return {
+    kind: 'runtime-plugin',
+    ...(pkg === undefined ? {} : { pkg }),
+    ...(verdict.pluginName === undefined ? {} : { pluginName: verdict.pluginName }),
+  };
+}
+
+export interface PackageRouter {
+  packageRouteOf(options: RouteOptions): Promise<PackageRoute | undefined>;
+  reset(): void;
+}
+
+interface RouteOptions {
+  readonly spec: string;
+  readonly shell?: DshShell | undefined;
+  readonly registry?: string | undefined;
+  readonly force?: boolean;
+}
+
+export interface PackageRouterOptions {
+  readonly manifestFile: string;
+  readonly cacheDir?: string | undefined;
+  readonly dshLookup?: ((options: { shell: DshShell; name: string; registry: string }) => Promise<{ readable: boolean; raw: unknown }>) | undefined;
+}
+
+export function createPackageRouter(options: PackageRouterOptions): PackageRouter {
+  const cache = new Map<string, { at: number; route: PackageRoute | null }>();
+  return {
+    packageRouteOf: (routeOptions) => routeOf(cache, options, routeOptions),
+    reset: () => {
+      cache.clear();
+    },
+  };
+}
+
+async function routeOf(
+  cache: Map<string, { at: number; route: PackageRoute | null }>,
+  options: PackageRouterOptions,
+  routeOptions: RouteOptions,
+): Promise<PackageRoute | undefined> {
+  const local = localDirOf(routeOptions.spec);
+  if (local !== undefined) {
+    const verdict = verdictOf(local, options.manifestFile);
+    return verdict === undefined ? undefined : routeOfVerdict(verdict, splitNpmSpec(routeOptions.spec)?.name);
+  }
+
+  const ref = splitNpmSpec(routeOptions.spec);
+  if (ref === undefined) return undefined;
+  const shell = routeOptions.shell;
+  const registry = routeOptions.registry;
+  if (shell === undefined || registry === undefined) return undefined;
+
+  const key = `${registry}|${routeOptions.spec}`;
+  const hit = cache.get(key);
+  if (routeOptions.force !== true && hit !== undefined && Date.now() - hit.at < VERSION_CHECK_TTL_MS) {
+    return hit.route ?? undefined;
+  }
+
+  const found =
+    options.dshLookup === undefined
+      ? { readable: false, raw: undefined }
+      : await options.dshLookup({ shell, name: routeOptions.spec, registry });
+  let route: PackageRoute | undefined;
+  if (found.readable && dshMarkersOf(found.raw)) {
+    route = { kind: 'dsh-bundle' };
+  } else {
+    const verdict = await withPackageDir(
+      { shell, spec: routeOptions.spec, registry, ...(options.cacheDir === undefined ? {} : { cacheDir: options.cacheDir }) },
+      (dir) => verdictOf(dir, options.manifestFile),
+    );
+    route = verdict === undefined ? undefined : routeOfVerdict(verdict, ref.name);
+  }
+  cache.set(key, { at: Date.now(), route: route ?? null });
+  return route;
+}