deepseek-harness/packages/boot/plugin-manager/src/modules.ts

/**
 * The modules a package offers a composition: how a declared `dsh.plugins`
 * entry is named as a row and derived into a row id, and its wire view.
 * @module @deepseek-ai/dsh-plugin-manager/modules
 */

import type { PluginProbe } from '@deepseek-ai/dsh-app-boot'
import type { JsonValue } from '@deepseek-ai/dsh-util-values'
import { optional } from './helpers.ts'
import type { PluginPackageAddableView } from './types.ts'

/**
 * The row `name` for one declared addable module.
 * @param packageName - the package.
 * @param declared - the `dsh.plugins[].name`, `.` for the main export.
 * @returns the bare package for `.`, else `<package>/<subpath>`.
 */
export function moduleSpecifier(packageName: string, declared: string): string {
  if (declared === '.') return packageName
  return `${packageName}/${declared.replace(/^\.\//, '')}`
}

/**
 * The row id derived from a package name and module: the unscoped name, then the subpath.
 * @param packageName - the package.
 * @param declared - the `dsh.plugins[].name`, `.` for the main export.
 * @returns the row id.
 */
export function derivedRowId(packageName: string, declared: string): string {
  const base = packageName.replace(/^@/, '')
  return declared === '.' ? base : `${base}/${declared.replace(/^\.\//, '')}`
}

/**
 * The modules a package offers a composition: what it declares in
 * `dsh.plugins`, and — for a plugin module — its main export as `.`, the
 * implicit entry `PluginManager.addRow` accepts without a declaration.
 * @param packageName - the package.
 * @param probe - the package's probe record, when one exists.
 * @returns the declared modules, with `.` first for a plugin module that does not declare it.
 */
export function addableViews(packageName: string, probe: PluginProbe | undefined): PluginPackageAddableView[] {
  const declared = (probe?.addable ?? []).map(entry => addableView(packageName, entry))
  if (probe?.kind !== 'plugin' || declared.some(entry => entry.declaredName === '.')) return declared
  return [{
    moduleName: packageName,
    declaredName: '.',
    ...optional('title', probe.title),
    ok: probe.ok,
    ...optional('error', probe.reason),
    ...optional('configSchema', probe.configSchema as JsonValue | undefined),
  }, ...declared]
}

/**
 * The wire view of one probed addable module.
 * @param packageName - the package.
 * @param entry - the probe's record of the declared module.
 * @returns the view.
 */
export function addableView(packageName: string, entry: PluginProbe['addable'][number]): PluginPackageAddableView {
  return {
    moduleName: moduleSpecifier(packageName, entry.name),
    declaredName: entry.name,
    ...optional('title', entry.title),
    // The probe read both from JSON: a manifest field and a child's report.
    ...optional('config', entry.config as JsonValue | undefined),
    ok: entry.ok,
    ...optional('error', entry.error),
    ...optional('configSchema', entry.configSchema as JsonValue | undefined),
  }
}