@dsh-workbench/shared 1.1.7 → 1.1.9

package/src/host/plugin-ledger.ts

@@ -3,7 +3,7 @@ import type { ModuleStore } from './workspace-store.js';
 export const PLUGIN_LEDGER_FILE = 'plugins.json';
 
 export interface PluginLedgerEntry {
-  readonly opencliHome: string;
+  readonly home: string;
   readonly package: string;
   readonly name?: string;
   readonly registry?: string;
@@ -13,10 +13,10 @@ export interface PluginLedgerEntry {
 }
 
 export function ledgerKeyOf(entry: {
-  readonly opencliHome: string;
+  readonly home: string;
   readonly package: string;
 }): string {
-  return `${entry.opencliHome}\u0000${entry.package}`;
+  return `${entry.home}\u0000${entry.package}`;
 }
 
 function textOf(value: unknown): string | undefined {
@@ -25,18 +25,25 @@ function textOf(value: unknown): string | undefined {
   return trimmed === '' ? undefined : trimmed;
 }
 
+function legacyHomeOf(box: Readonly<Record<string, unknown>>): unknown {
+  for (const [key, value] of Object.entries(box)) {
+    if (key !== 'home' && key.toLowerCase().endsWith('home')) return value;
+  }
+  return undefined;
+}
+
 function entryOf(value: unknown): PluginLedgerEntry | undefined {
   if (typeof value !== 'object' || value === null) return undefined;
   const box = value as Readonly<Record<string, unknown>>;
-  const opencliHome = textOf(box['opencliHome']);
+  const home = textOf(box['home']) ?? textOf(legacyHomeOf(box));
   const pkg = textOf(box['package']);
   const installedAt = textOf(box['installedAt']);
-  if (opencliHome === undefined || pkg === undefined || installedAt === undefined) return undefined;
+  if (home === undefined || pkg === undefined || installedAt === undefined) return undefined;
   const name = textOf(box['name']);
   const registry = textOf(box['registry']);
   const releasedAt = textOf(box['releasedAt']);
   return {
-    opencliHome,
+    home,
     package: pkg,
     installedAt,
     ...(name === undefined ? {} : { name }),
@@ -74,9 +81,9 @@ export function writePluginLedger(store: ModuleStore, entries: readonly PluginLe
 
 export function pluginEntriesOfHome(
   entries: readonly PluginLedgerEntry[],
-  opencliHome: string,
+  home: string,
 ): PluginLedgerEntry[] {
-  return entries.filter((entry) => entry.opencliHome === opencliHome);
+  return entries.filter((entry) => entry.home === home);
 }
 
 export function isHeldEntry(entry: PluginLedgerEntry): boolean {
@@ -85,30 +92,30 @@ export function isHeldEntry(entry: PluginLedgerEntry): boolean {
 
 export function heldEntriesOfHome(
   entries: readonly PluginLedgerEntry[],
-  opencliHome: string,
+  home: string,
 ): PluginLedgerEntry[] {
-  return pluginEntriesOfHome(entries, opencliHome).filter(isHeldEntry);
+  return pluginEntriesOfHome(entries, home).filter(isHeldEntry);
 }
 
 export function heldEntryOfPlugin(
   entries: readonly PluginLedgerEntry[],
-  opencliHome: string,
+  home: string,
   plugin: string,
 ): PluginLedgerEntry | undefined {
   const key = plugin.trim();
   if (key === '') return undefined;
-  return heldEntriesOfHome(entries, opencliHome).find(
+  return heldEntriesOfHome(entries, home).find(
     (entry) => entry.name === key || entry.package === key,
   );
 }
 
 export function withReleasedEntry(
   entries: readonly PluginLedgerEntry[],
-  opencliHome: string,
+  home: string,
   pkg: string,
   releasedAt: string,
 ): PluginLedgerEntry[] {
-  const entry = pluginEntryOf(entries, opencliHome, pkg);
+  const entry = pluginEntryOf(entries, home, pkg);
   if (entry === undefined || entry.releasedAt !== undefined) return [...entries];
   return withPluginEntry(entries, { ...entry, releasedAt });
 }
@@ -127,10 +134,10 @@ export function pluginRetentionOf(options: {
 
 export function pluginEntryOf(
   entries: readonly PluginLedgerEntry[],
-  opencliHome: string,
+  home: string,
   pkg: string,
 ): PluginLedgerEntry | undefined {
-  const key = ledgerKeyOf({ opencliHome, package: pkg });
+  const key = ledgerKeyOf({ home, package: pkg });
   return entries.find((entry) => ledgerKeyOf(entry) === key);
 }
 
@@ -144,9 +151,9 @@ export function withPluginEntry(
 
 export function withoutPluginEntry(
   entries: readonly PluginLedgerEntry[],
-  opencliHome: string,
+  home: string,
   pkg: string,
 ): PluginLedgerEntry[] {
-  const key = ledgerKeyOf({ opencliHome, package: pkg });
+  const key = ledgerKeyOf({ home, package: pkg });
   return entries.filter((entry) => ledgerKeyOf(entry) !== key);
 }

package/src/host/plugin.ts

@@ -1,7 +1,6 @@
 import { readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 
-export const OPENCLI_MANIFEST_FILE = 'opencli-plugin.json';
 
 function asRecord(value: unknown): Readonly<Record<string, unknown>> | undefined {
   return typeof value === 'object' && value !== null ? (value as Readonly<Record<string, unknown>>) : undefined;
@@ -13,9 +12,9 @@ function isCommandFile(name: string): boolean {
   return name.endsWith('.ts') || name.endsWith('.js');
 }
 
-function pluginManifestOf(dir: string): Readonly<Record<string, unknown>> | undefined {
+function pluginManifestOf(dir: string, manifestFile: string): Readonly<Record<string, unknown>> | undefined {
   try {
-    const parsed: unknown = JSON.parse(readFileSync(join(dir, OPENCLI_MANIFEST_FILE), 'utf8'));
+    const parsed: unknown = JSON.parse(readFileSync(join(dir, manifestFile), 'utf8'));
     if (Array.isArray(parsed)) return undefined;
     return asRecord(parsed);
   } catch {
@@ -31,8 +30,8 @@ function hasCommandFile(dir: string): boolean {
   }
 }
 
-export function pluginAt(dir: string): { readonly name?: string } | undefined {
-  const manifest = pluginManifestOf(dir);
+export function pluginAt(dir: string, manifestFile: string): { readonly name?: string } | undefined {
+  const manifest = pluginManifestOf(dir, manifestFile);
   if (manifest === undefined || !hasCommandFile(dir)) return undefined;
   const name = manifest.name;
   return typeof name === 'string' && name.trim() !== '' ? { name: name.trim() } : {};

package/src/host/port-types.ts

@@ -1,19 +1,23 @@
 import type { DshHostContext, DshShell } from '../api/dsh.js';
+import type { RuntimeCapabilities, RuntimeProfile } from '../contract/capabilities.js';
+import type { PluginPackageKind } from '../contract/protocol/bundle-install.js';
 import type { LibNeed, SupplySource } from '../contract/needs.js';
 import type { NeedProbeInput, UnitCapability } from '../contract/unit-capability.js';
+import type { DataReader } from '../contract/data.js';
+import type { LibRunner } from '../contract/runner.js';
 import type { WorkbenchSelfUpdate } from '../contract/protocol/bundle-install.js';
 import type {
   BundleManager,
   InstalledModule,
-  OpencliResolution,
   ProfileModule,
   ProfilePackage,
   RegistryNotebook,
+  RuntimeStatus,
   SelfUpdateRequest,
   SelfUpdateStart,
 } from './adapter-types.js';
 import type { PostResource, RouteHandler, RouteTable } from './http.js';
-import type { PluginSourceOptions, ResolvedPluginSource } from './plugin-source.js';
+import type { PluginSourceOptions, ResolvedPluginSource } from '../contract/plugin-source.js';
 
 export interface LoggerLike {
   info?(message: string): void;
@@ -29,7 +33,7 @@ export interface ProfilePort {
 export type SupplyPluginSource = ResolvedPluginSource;
 
 export interface SupplyPackageRoute {
-  readonly kind: 'opencli-plugin' | 'dsh-bundle' | 'neither';
+  readonly kind: PluginPackageKind | 'dsh-bundle' | 'neither';
   readonly pkg?: string;
   readonly pluginName?: string;
 }
@@ -85,6 +89,7 @@ export interface EnvSupplyPort {
     readonly source: Extract<SupplySource, { kind: 'npm' }>;
     readonly version?: string | undefined;
   }): string;
+  libUninstallCommand(options: { readonly need: LibNeed }): string;
   pluginInstallPlan(options: SupplyPluginInstallOptions): ResolvedPluginSource;
   latestVersion(options: SupplyLatestOptions): Promise<string | undefined>;
   missingReleaseParts(options: SupplyMissingPartsOptions): Promise<readonly string[]>;
@@ -93,10 +98,14 @@ export interface EnvSupplyPort {
 }
 
 export interface ModulePort {
+  isolatedRoot(): string;
   isolatedHome(): string;
-  cliCatalogPath(): string;
-  vendorPluginsDir(): string;
-  opencliInstallCommand(): string;
+  pluginPackagePrefix?(): string;
+  pluginManifestFile?(): string;
+  cliCatalogPath?(): string;
+  vendorPluginsDir?(): string;
+  runtimeInstallCommand?(): string;
+  afterLibInstall(): void;
   profileDirOf(ctx: DshHostContext): string | null;
   profileModules(dir: string | null): readonly ProfileModule[];
   readInstalledModule(dir: string | null, pkg: string): InstalledModule;
@@ -140,8 +149,10 @@ export interface ProbePreflightInput {
   readonly routes: RouteTable;
   readonly ctx: DshHostContext;
   readonly shell: DshShell;
-  readonly opencliCommand: string;
-  readonly installCommand?: string | undefined;
+  readonly runtimeCommands: Readonly<Record<string, string>>;
+  readonly runtimeCapabilities: RuntimeCapabilities;
+  readonly runtimeCheck?: (() => Promise<RuntimeCheck>) | undefined;
+  readonly runtimeLabel?: string | undefined;
   readonly warmReads: () => readonly (readonly string[])[];
 }
 
@@ -156,9 +167,32 @@ export interface RuntimeSeedOptions {
   readonly log: (message: string) => void;
 }
 
+export type { RuntimeCapabilities, RuntimeProfile, RuntimeTerms } from '../contract/capabilities.js';
+
+export interface RuntimeCheck {
+  readonly ok: boolean;
+  readonly detail: string;
+}
+
+export interface RuntimeCommandSurface {
+  readonly name: string;
+  readonly pluginPrefix: string;
+  invoke(site: string, command?: string): string;
+  help(site: string): string;
+  browser?(verb: readonly string[]): string;
+  background?(command: string, argv: readonly string[]): string;
+  readonly authorHint?: string;
+}
+
 export interface RuntimePort {
   packageRoot(moduleUrl: string): string;
-  opencliCommand(ctx: DshHostContext): OpencliResolution;
+  capabilities(ctx: DshHostContext): RuntimeCapabilities;
+  profile?(ctx: DshHostContext): RuntimeProfile;
+  commandSurface?(ctx: DshHostContext): RuntimeCommandSurface | undefined;
+  check?(ctx: DshHostContext): Promise<RuntimeCheck>;
+  commands(ctx: DshHostContext): Readonly<Record<string, string>>;
+  runners(ctx: DshHostContext, data: DataReader): Readonly<Record<string, LibRunner>>;
+  health(ctx: DshHostContext): Readonly<Record<string, RuntimeStatus>>;
   seed(ctx: DshHostContext, options: RuntimeSeedOptions): void;
   warnUnwritableRoot(ctx: DshHostContext): void;
 }

package/src/host/preflight.ts

@@ -1,11 +1,12 @@
-export type PreflightStepId = 'toolchain' | 'opencli' | 'bridge' | 'diy' | 'warm';
+export type PreflightStepId = 'toolchain' | 'cli' | 'bridge' | 'runtime' | 'diy' | 'warm';
 export type PreflightStepStatus = 'pending' | 'running' | 'ok' | 'warn' | 'failed';
 export type PreflightFailure = 'permission' | 'network' | 'missing' | 'unknown';
 export type PreflightGuidance = 'install' | 'path' | 'shell';
-export type PreflightBridgeIssue = 'daemon' | 'extension' | 'profile' | 'stale' | 'unknown';
+export type PreflightBridgeIssue = string;
 
 export interface PreflightStep {
   readonly id: PreflightStepId;
+  readonly label?: string;
   readonly status: PreflightStepStatus;
   readonly detail?: string;
   readonly action?: string;

package/src/host/profile-create.ts

@@ -0,0 +1,133 @@
+import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import type { PostResource, RouteHandler } from './http.js';
+import { quoteShellArg } from './shell-text.js';
+import type {
+  ProfileCreateApplied,
+  ProfileCreateProfile,
+  ProfileCreateSnapshot,
+} from '../contract/protocol/profile-create.js';
+import { PROFILE_CREATE_RESOURCE } from '../contract/protocol/profile-create.js';
+
+const PROFILE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const BUNDLE = '@dsh-workbench/core';
+
+export interface ProfileCreateDeps {
+  readonly home: string;
+  readonly self: string;
+  readonly packageRoot: string;
+  readonly runSetup?: ((env: Readonly<Record<string, string>>) => Promise<{ ok: boolean; log: string }>) | undefined;
+}
+
+function textOf(value: unknown): string {
+  return typeof value === 'string' ? value : '';
+}
+
+function profileNames(profilesDir: string): readonly string[] {
+  try {
+    return readdirSync(profilesDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
+      .map((entry) => entry.name)
+      .filter((name) => existsSync(join(profilesDir, name, 'package.json')))
+      .sort((a, b) => a.localeCompare(b));
+  } catch {
+    return [];
+  }
+}
+
+export function profileCreateSnapshot(deps: ProfileCreateDeps): ProfileCreateSnapshot {
+  const profiles: ProfileCreateProfile[] = profileNames(join(deps.home, 'profiles')).map((name) => ({
+    name,
+    current: name === deps.self,
+    readable: true,
+  }));
+  return { current: deps.self, profiles };
+}
+
+export function profileCreateHandler(deps: ProfileCreateDeps): RouteHandler {
+  return () => ({ ok: true, ...profileCreateSnapshot(deps) });
+}
+
+function inside(base: string, path: string): boolean {
+  const root = resolve(base);
+  const target = resolve(path);
+  return target === root ? false : target.startsWith(`${root}${sep}`);
+}
+
+export async function profileCreateApply(
+  deps: ProfileCreateDeps,
+  payload: unknown,
+): Promise<ProfileCreateApplied | { ok: false; text: string }> {
+  const body = typeof payload === 'object' && payload !== null ? (payload as Record<string, unknown>) : {};
+  const profile = textOf(body['profile']).trim();
+  const source = textOf(body['source']).trim();
+  const copy = typeof body['copy'] === 'object' && body['copy'] !== null ? (body['copy'] as Record<string, unknown>) : {};
+  const flags = {
+    settings: copy['settings'] === true,
+  };
+  if (!PROFILE_NAME.test(profile)) return { ok: false, text: '新工作台的名字不合法：只用字母、数字、点、下划线或短横线' };
+  if (source === '') return { ok: false, text: '先选一个来源 profile' };
+  if (source === profile) return { ok: false, text: '来源不能是新工作台自己' };
+  const profilesDir = join(deps.home, 'profiles');
+  if (!profileNames(profilesDir).includes(source)) return { ok: false, text: `没有这个 profile：${source}` };
+  if (existsSync(join(profilesDir, profile))) return { ok: false, text: `已经有一个叫 ${profile} 的 profile` };
+  const targetHome = join(deps.home, profile);
+  if (existsSync(targetHome)) return { ok: false, text: `运行时目录已经存在：${targetHome}` };
+  const env = {
+    DSH_HOME: deps.home,
+    DSH_WORKBENCH_HOME: targetHome,
+    WORKBENCH_PROFILE: profile,
+    WORKBENCH_SOURCE_PROFILE: source,
+    WB_CLONE: '1',
+    WB_COPY_SETTINGS: flags.settings ? '1' : '0',
+  };
+  const setup = deps.runSetup;
+  if (setup === undefined) {
+    return { ok: false, text: '这台机器上没有装工作台的脚本入口，建不了新的工作台。' };
+  }
+  const cleanup = (): void => {
+    try {
+      if (inside(profilesDir, join(profilesDir, profile))) rmSync(join(profilesDir, profile), { recursive: true, force: true });
+      if (inside(deps.home, targetHome)) rmSync(targetHome, { recursive: true, force: true });
+    } catch {
+      return;
+    }
+  };
+  const result = await setup(env);
+  if (!result.ok) {
+    cleanup();
+    return { ok: false, text: `创建失败：${result.log.trim().slice(-1200) || 'setup 没给出原因'}` };
+  }
+  try {
+    const manifest = JSON.parse(readFileSync(join(profilesDir, profile, 'package.json'), 'utf8')) as {
+      dsh?: { profile?: { bundles?: unknown } };
+    };
+    const bundles = manifest.dsh?.profile?.bundles;
+    if (!Array.isArray(bundles) || !bundles.includes(BUNDLE)) {
+      cleanup();
+      return { ok: false, text: 'profile 建好了，但工作台 bundle 没被选中；先跑一次 setup 修好它' };
+    }
+  } catch (error) {
+    cleanup();
+    return { ok: false, text: `profile 建好了，但读不了清单：${error instanceof Error ? error.message : String(error)}` };
+  }
+  const copied = Object.entries(flags)
+    .filter(([, on]) => on)
+    .map(([name]) => name);
+  const bin = join(deps.packageRoot, 'bin', 'dsh-workbench');
+  return {
+    ok: true,
+    profile,
+    source,
+    home: targetHome,
+    command: `WORKBENCH_PROFILE=${quoteShellArg(profile)} ${quoteShellArg(bin)}`,
+    copied,
+  };
+}
+
+export function profileCreateAction(deps: ProfileCreateDeps): PostResource {
+  return {
+    resource: PROFILE_CREATE_RESOURCE,
+    handle: (payload: unknown) => profileCreateApply(deps, payload),
+  };
+}

package/src/host/profile-registries.ts

@@ -0,0 +1,145 @@
+import type { RegistryEntry, RegistryNotebook } from './adapter-types.js';
+import { normalizeRegistry, sameRegistry, scopeOf } from './adapter-types.js';
+import fs from 'node:fs';
+import path from 'node:path';
+export const REGISTRY_MARKER =
+  '# dsh-workbench 写的：这一行的包只在这个源上（dsh 卸载没有源参数，pnpm 得问得到）';
+
+function registryRootOf(name: string, tarball: string): string | null {
+  const at = tarball.indexOf(`/${name}/-/`);
+  if (at > 0) return normalizeRegistry(tarball.slice(0, at));
+  try {
+    return normalizeRegistry(new URL(tarball).origin);
+  } catch {
+    return null;
+  }
+}
+
+const PACKAGE_KEY = /^ {2}'?(\S+)'?:\s*$/;
+const PACKAGE_NAME = /^(?:@[^/\s]+\/)?[^/\s@]+$/;
+const TARBALL = /tarball:\s*(\S+?)\}?\s*$/;
+
+export function sourcesFromLockfile(text: string): readonly RegistryEntry[] {
+  const found = new Map<string, string | null>();
+  let name: string | null = null;
+  for (const line of text.split('\n')) {
+    const key = PACKAGE_KEY.exec(line);
+    if (key !== null) {
+      const raw = key[1] ?? '';
+      const at = raw.lastIndexOf('@');
+      const candidate = at > 0 ? raw.slice(0, at) : '';
+      name = PACKAGE_NAME.test(candidate) ? candidate : null;
+      continue;
+    }
+    if (name === null) continue;
+    const tarball = TARBALL.exec(line);
+    if (tarball === null) continue;
+    const scope = scopeOf(name);
+    const root = registryRootOf(name, tarball[1] ?? '');
+    name = null;
+    if (scope === null || root === null) continue;
+    const seen = found.get(scope);
+    if (seen === undefined) found.set(scope, root);
+    else if (!sameRegistry(seen, root)) found.set(scope, null);
+  }
+  return [...found.entries()]
+    .filter((entry): entry is [string, string] => entry[1] !== null)
+    .map(([scope, registry]) => ({ scope, registry }));
+}
+
+export interface RegistryConfigMerge {
+  readonly text: string;
+  readonly added: readonly string[];
+}
+
+export function mergeRegistryConfig(text: string, entries: readonly RegistryEntry[]): RegistryConfigMerge {
+  const lines = text.split('\n');
+  const present = (key: string): boolean => lines.some((line) => line.trim().startsWith(`${key}=`));
+  const appended: string[] = [];
+  const added: string[] = [];
+  for (const entry of entries) {
+    const key = `${entry.scope}:registry`;
+    if (entry.registry.trim() === '' || present(key)) continue;
+    lines.push(`${key}=${normalizeRegistry(entry.registry)}`);
+    appended.push(`${key}=${normalizeRegistry(entry.registry)}`);
+    added.push(key);
+  }
+  if (appended.length === 0) return { text, added: [] };
+  const base = text === '' ? '' : text.endsWith('\n') ? text : `${text}\n`;
+  const marker = base.includes(REGISTRY_MARKER) ? '' : `${REGISTRY_MARKER}\n`;
+  return { text: `${base}${marker}${appended.join('\n')}\n`, added };
+}
+
+export function replaceScopeRegistry(text: string, scope: string, registry: string): string {
+  const key = `${scope}:registry`;
+  const value = normalizeRegistry(registry);
+  let found = false;
+  const lines = text.split('\n').map((line) => {
+    if (!line.trim().startsWith(`${key}=`)) return line;
+    found = true;
+    return `${key}=${value}`;
+  });
+  if (found) return lines.join('\n');
+  const base = text === '' ? '' : text.endsWith('\n') ? text : `${text}\n`;
+  return `${base}${key}=${value}\n`;
+}
+
+function readNpmrc(file: string): string {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function writeNpmrc(file: string, text: string): void {
+  const temp = `${file}.dsh-workbench.tmp`;
+  fs.writeFileSync(temp, text, { mode: 0o600 });
+  fs.renameSync(temp, file);
+}
+
+export function createRegistryNotebook(dir: string | null): RegistryNotebook {
+  return {
+    sources() {
+      if (dir === null) return [];
+      try {
+        return sourcesFromLockfile(fs.readFileSync(path.join(dir, 'pnpm-lock.yaml'), 'utf8'));
+      } catch {
+        return [];
+      }
+    },
+    remember(entries) {
+      if (dir === null || entries.length === 0) return [];
+      const file = path.join(dir, '.npmrc');
+      const merged = mergeRegistryConfig(readNpmrc(file), entries);
+      if (merged.added.length === 0) return [];
+      writeNpmrc(file, merged.text);
+      return merged.added;
+    },
+    swapScope(scope, registry) {
+      if (dir === null || scope.trim() === '' || registry.trim() === '') return () => {};
+      const file = path.join(dir, '.npmrc');
+      const key = `${scope.trim()}:registry`;
+      const value = normalizeRegistry(registry);
+      const before = readNpmrc(file);
+      const previous = before.split('\n').find((line) => line.trim().startsWith(`${key}=`));
+      const after = replaceScopeRegistry(before, scope.trim(), registry);
+      if (after === before) return () => {};
+      writeNpmrc(file, after);
+      return () => {
+        const now = readNpmrc(file);
+        if (now === after) {
+          if (before === '') fs.rmSync(file, { force: true });
+          else writeNpmrc(file, before);
+          return;
+        }
+        if (!now.includes(`${key}=${value}`)) return;
+        const restored =
+          previous === undefined
+            ? now.split('\n').filter((line) => !line.trim().startsWith(`${key}=`)).join('\n')
+            : now.replace(`${key}=${value}`, previous);
+        writeNpmrc(file, restored);
+      };
+    },
+  };
+}

package/src/host/registry-declaration.ts

@@ -0,0 +1,70 @@
+import type { DshShell } from '../api/dsh.js';
+import { runShell } from './shell.js';
+import { quoteShellArg } from './shell-text.js';
+import { parseJsonLoose } from '../lib/text.js';
+import { VERSION_CHECK_TIMEOUT_MS, VERSION_CHECK_TTL_MS } from '../config/constants.js';
+
+function recordOf(value: unknown): Readonly<Record<string, unknown>> | undefined {
+  return typeof value === 'object' && value !== null ? (value as Readonly<Record<string, unknown>>) : undefined;
+}
+
+export interface RegistryDshLookup {
+  readonly readable: boolean;
+  readonly raw: unknown;
+}
+
+export interface RegistryLookup {
+  registryDshOf(options: RegistryDshOptions): Promise<RegistryDshLookup>;
+  registryDeclarationOf(options: RegistryDeclarationOptions): Promise<unknown | undefined>;
+}
+
+interface RegistryDshOptions {
+  readonly shell: DshShell;
+  readonly name: string;
+  readonly registry?: string | undefined;
+  readonly force?: boolean;
+  readonly cacheDir?: string | undefined;
+}
+
+interface RegistryDeclarationOptions extends RegistryDshOptions {
+  readonly registry: string;
+}
+
+export function createRegistryLookup(): RegistryLookup {
+  const cache = new Map<string, { at: number; raw: unknown }>();
+  return {
+    registryDshOf: (options) => dshOf(cache, options),
+    registryDeclarationOf: async (options) => {
+      const found = await dshOf(cache, options);
+      return found.readable ? recordOf(found.raw)?.workbench : undefined;
+    },
+  };
+}
+
+async function dshOf(cache: Map<string, { at: number; raw: unknown }>, options: {
+  shell: DshShell;
+  name: string;
+  registry?: string | undefined;
+  force?: boolean;
+  cacheDir?: string | undefined;
+}): Promise<RegistryDshLookup> {
+  const { shell, name, registry, force = false, cacheDir } = options;
+  const key = `${registry ?? ''}|${name}`;
+  const hit = cache.get(key);
+  if (!force && hit !== undefined && Date.now() - hit.at < VERSION_CHECK_TTL_MS) {
+    return { readable: true, raw: hit.raw };
+  }
+
+  const at = registry === undefined ? '' : ` --registry ${quoteShellArg(registry)}`;
+  const cached = cacheDir === undefined ? '' : ` --cache ${quoteShellArg(cacheDir)}`;
+  const result = await runShell(
+    shell,
+    `npm view ${quoteShellArg(name)} dsh --json${at}${cached}`,
+    { timeoutMs: VERSION_CHECK_TIMEOUT_MS },
+  ).catch(() => undefined);
+  const parsed = result?.exitCode === 0 ? parseJsonLoose(result.stdout) : undefined;
+  if (parsed === undefined) return { readable: false, raw: undefined };
+  cache.set(key, { at: Date.now(), raw: parsed });
+  return { readable: true, raw: parsed };
+}
+