@dsh-workbench/shared 0.3.11 → 1.0.0-beta.1

package/src/host/adapter-set.ts

@@ -0,0 +1,299 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { DshHostContext } from '../api/dsh.js';
+import {
+  ADAPTER_SET_API_VERSION,
+  SUPPORTED_ADAPTER_API_VERSIONS,
+  type AdapterSet,
+  type CoreAdapterSet,
+} from './adapters.js';
+import { isPackageName } from './spec.js';
+
+export interface WorkbenchConfig {
+  readonly adapterSet?: string;
+}
+
+export type AdapterSetFailure =
+  | 'not-configured'
+  | 'no-profile'
+  | 'malformed'
+  | 'not-resolvable'
+  | 'import-failed'
+  | 'bad-export'
+  | 'factory-failed'
+  | 'incompatible-version'
+  | 'missing-member';
+
+export type AdapterSetLoad =
+  | { readonly ok: true; readonly spec: string; readonly set: CoreAdapterSet }
+  | {
+      readonly ok: false;
+      readonly spec?: string;
+      readonly failure: AdapterSetFailure;
+      readonly detail: string;
+      readonly cause?: unknown;
+    };
+
+const CORE_MEMBERS = ['data', 'supply', 'profile', 'probe'] as const;
+
+const CORE_METHODS = [
+  ['data', 'read'],
+  ['data', 'request'],
+  ['data', 'requestMany'],
+  ['data', 'submit'],
+  ['supply', 'resolvePluginSource'],
+  ['supply', 'libInstallCommand'],
+  ['supply', 'pluginInstallPlan'],
+  ['supply', 'latestVersion'],
+  ['supply', 'missingReleaseParts'],
+  ['supply', 'probeRelease'],
+  ['supply', 'splitNpmSpec'],
+  ['profile', 'dirOf'],
+  ['profile', 'dshPlugins'],
+  ['profile', 'selfUpdateView'],
+  ['probe', 'probeUnits'],
+  ['probe', 'registerPreflight'],
+  ['probe', 'declaredPluginCommands'],
+] as const;
+
+const FULL_MEMBERS = ['modules', 'runtime', 'plugins', 'actions'] as const;
+
+const FULL_METHODS = [
+  ['modules', 'isolatedHome'],
+  ['modules', 'cliCatalogPath'],
+  ['modules', 'vendorPluginsDir'],
+  ['modules', 'opencliInstallCommand'],
+  ['modules', 'profileDirOf'],
+  ['modules', 'profileModules'],
+  ['modules', 'readInstalledModule'],
+  ['modules', 'readProfilePackage'],
+  ['modules', 'readBundleManager'],
+  ['modules', 'createRegistryNotebook'],
+  ['modules', 'declarationGaps'],
+  ['modules', 'moduleDeclarationOf'],
+  ['modules', 'registryDeclarationOf'],
+  ['modules', 'pathDeclarationOf'],
+  ['modules', 'declarationRefusalOf'],
+  ['modules', 'refusalReason'],
+  ['modules', 'packageRouteOf'],
+  ['modules', 'isNewerVersion'],
+  ['modules', 'startSelfUpdate'],
+  ['runtime', 'packageRoot'],
+  ['runtime', 'opencliCommand'],
+  ['runtime', 'seed'],
+  ['runtime', 'warnUnwritableRoot'],
+  ['plugins', 'declarationLookup'],
+  ['plugins', 'createUnits'],
+  ['actions', 'configSyncHandler'],
+  ['actions', 'profileCreateHandler'],
+  ['actions', 'configSyncAction'],
+  ['actions', 'profileCreateAction'],
+] as const;
+
+function methodOf(value: Record<string, unknown>, member: string, method: string): unknown {
+  const part = value[member];
+  if (typeof part !== 'object' || part === null) return undefined;
+  return (part as Record<string, unknown>)[method];
+}
+
+function failure(
+  failureKind: AdapterSetFailure,
+  detail: string,
+  spec?: string,
+  cause?: unknown,
+): AdapterSetLoad {
+  return {
+    ok: false,
+    ...(spec === undefined ? {} : { spec }),
+    failure: failureKind,
+    detail,
+    ...(cause === undefined ? {} : { cause }),
+  };
+}
+
+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 packageDirOf(spec: string, from: string): string | undefined {
+  let dir = from;
+  for (;;) {
+    const candidate = join(dir, 'node_modules', spec);
+    if (existsSync(join(candidate, 'package.json'))) return candidate;
+    const up = dirname(dir);
+    if (up === dir) return undefined;
+    dir = up;
+  }
+}
+
+function entryOf(value: unknown): string | undefined {
+  if (typeof value === 'string') return value;
+  if (typeof value !== 'object' || value === null) return undefined;
+  const record = value as Record<string, unknown>;
+  for (const key of ['import', 'node', 'module', 'default', 'require']) {
+    const found = entryOf(record[key]);
+    if (found !== undefined) return found;
+  }
+  return undefined;
+}
+
+function exportsEntryOf(value: unknown): string | undefined {
+  if (typeof value !== 'object' || value === null) return entryOf(value);
+  const record = value as Record<string, unknown>;
+  return '.' in record ? entryOf(record['.']) : entryOf(record);
+}
+
+function esmEntryUrl(spec: string, profileDir: string): string | undefined {
+  const dir = packageDirOf(spec, profileDir);
+  if (dir === undefined) return undefined;
+  let pkg: Record<string, unknown>;
+  try {
+    pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+  const main = typeof pkg['main'] === 'string' ? pkg['main'] : undefined;
+  const module = typeof pkg['module'] === 'string' ? pkg['module'] : undefined;
+  const entry = exportsEntryOf(pkg['exports']) ?? module ?? main ?? 'index.js';
+  const file = join(dir, entry);
+  return existsSync(file) ? pathToFileURL(file).href : undefined;
+}
+
+function resolveFromProfile(spec: string, profileDir: string): string | undefined {
+  const esm = esmEntryUrl(spec, profileDir);
+  if (esm !== undefined) return esm;
+  const parent = pathToFileURL(join(profileDir, 'package.json')).href;
+  try {
+    return pathToFileURL(createRequire(parent).resolve(spec)).href;
+  } catch {
+    return undefined;
+  }
+}
+
+function versionOf(value: Record<string, unknown>): number | undefined {
+  const version = value['apiVersion'];
+  return typeof version === 'number' && Number.isInteger(version) ? version : undefined;
+}
+
+export function validateAdapterSet(value: unknown, spec: string): AdapterSetLoad {
+  if (typeof value !== 'object' || value === null) {
+    return failure('missing-member', `${spec} 的 createAdapterSet(ctx) 没回一个对象`, spec);
+  }
+  const record = value as Record<string, unknown>;
+  const version = versionOf(record);
+  if (version === undefined || !SUPPORTED_ADAPTER_API_VERSIONS.includes(version)) {
+    return failure(
+      'incompatible-version',
+      `${spec} 的适配器协议版本是 ${String(record['apiVersion'])}，工作台只认 v${ADAPTER_SET_API_VERSION}`,
+      spec,
+    );
+  }
+  const missing: string[] = CORE_MEMBERS.filter(
+    (member) => record[member] === undefined || record[member] === null,
+  );
+  for (const [member, method] of CORE_METHODS) {
+    if (typeof methodOf(record, member, method) !== 'function') missing.push(`${member}.${method}`);
+  }
+  if (typeof record['id'] !== 'string' || record['id'].trim() === '') missing.push('id');
+  if (typeof record['version'] !== 'string' || record['version'].trim() === '') missing.push('version');
+  if (FULL_MEMBERS.some((member) => record[member] !== undefined)) {
+    for (const member of FULL_MEMBERS) {
+      if (typeof record[member] !== 'object' || record[member] === null) missing.push(member);
+    }
+    for (const [member, method] of FULL_METHODS) {
+      if (typeof methodOf(record, member, method) !== 'function') missing.push(`${member}.${method}`);
+    }
+  }
+  if (missing.length > 0) {
+    return failure('missing-member', `${spec} 少了 ${missing.join(' / ')}`, spec);
+  }
+  return { ok: true, spec, set: record as unknown as CoreAdapterSet };
+}
+
+export async function loadAdapterSet(
+  ctx: DshHostContext,
+  spec: string | undefined,
+): Promise<AdapterSetLoad> {
+  const wanted = typeof spec === 'string' ? spec.trim() : spec === undefined ? '' : String(spec).trim();
+  if (wanted === '') return failure('not-configured', '没有配置 adapterSet');
+  const profileDir = profileDirOf(ctx);
+  if (profileDir === null) return failure('no-profile', '找不到 profile 目录，无法从 profile 解析适配器集合', wanted);
+  if (!isPackageName(wanted)) {
+    return failure('malformed', `适配器集合要写包名（如 @acme/adapters-set），收到 ${JSON.stringify(wanted)}`, wanted);
+  }
+
+  const url = resolveFromProfile(wanted, profileDir);
+  if (url === undefined) {
+    return failure('not-resolvable', `在 profile 里解析不到 ${wanted}，先把它装进这个 profile`, wanted);
+  }
+
+  let mod: Record<string, unknown>;
+  try {
+    mod = (await import(url)) as Record<string, unknown>;
+  } catch (error) {
+    return failure('import-failed', `${wanted} 的入口没加载成：${String(error)}`, wanted, error);
+  }
+
+  const factory = mod['createAdapterSet'] ?? mod['default'];
+  if (typeof factory !== 'function') {
+    return failure('bad-export', `${wanted} 没导出 createAdapterSet(ctx)，导出键：${Object.keys(mod).join(', ')}`, wanted);
+  }
+
+  let value: Record<string, unknown>;
+  try {
+    const raw: unknown = await factory(ctx);
+    if (typeof raw !== 'object' || raw === null) {
+      return failure('missing-member', `${wanted} 的 createAdapterSet(ctx) 没回一个对象`, wanted);
+    }
+    value = raw as Record<string, unknown>;
+  } catch (error) {
+    return failure('factory-failed', `${wanted} 的 createAdapterSet(ctx) 抛了：${String(error)}`, wanted, error);
+  }
+
+  return validateAdapterSet(value, wanted);
+}
+
+export function withDefaultAdapterSet(defaults: AdapterSet, loaded: AdapterSetLoad): AdapterSet {
+  if (!loaded.ok) return defaults;
+  const set = loaded.set as Partial<AdapterSet>;
+  return {
+    apiVersion: set.apiVersion ?? defaults.apiVersion,
+    id: set.id ?? defaults.id,
+    version: set.version ?? defaults.version,
+    data: set.data ?? defaults.data,
+    libs: set.libs ?? defaults.libs,
+    supply: set.supply ?? defaults.supply,
+    modules: set.modules ?? defaults.modules,
+    profile: set.profile ?? defaults.profile,
+    probe: set.probe ?? defaults.probe,
+    runtime: set.runtime ?? defaults.runtime,
+    plugins: set.plugins ?? defaults.plugins,
+    actions: set.actions ?? defaults.actions,
+  };
+}
+
+function isFullAdapterSet(value: CoreAdapterSet): value is AdapterSet {
+  const candidate = value as unknown as Record<string, unknown>;
+  return ['modules', 'runtime', 'plugins', 'actions'].every(
+    (member) => typeof candidate[member] === 'object' && candidate[member] !== null,
+  );
+}
+
+export async function resolveAdapterSet(
+  ctx: DshHostContext,
+  spec: string | undefined,
+  makeDefaults: () => Promise<AdapterSet>,
+): Promise<{ readonly set: AdapterSet; readonly load: AdapterSetLoad; readonly usedDefaults: boolean }> {
+  const load = await loadAdapterSet(ctx, spec);
+  if (load.ok && isFullAdapterSet(load.set)) {
+    return { set: load.set, load, usedDefaults: false };
+  }
+  const defaults = await makeDefaults();
+  return { set: withDefaultAdapterSet(defaults, load), load, usedDefaults: true };
+}
+
+export type { AdapterSet, CoreAdapterSet };

package/src/host/adapter-types.ts

@@ -0,0 +1,105 @@
+import type {
+  BundleCancellation,
+  BundleChange,
+  BundleInspection,
+  BundleInstallRequest,
+  BundleRegistries,
+  BundleRegistry,
+} from '../contract/protocol/bundle-install.js';
+
+export type InstalledModule =
+  | {
+      readonly kind: 'module';
+      readonly pkg: string;
+      readonly unit: string;
+      readonly version: string;
+      readonly registry?: string;
+      readonly local?: boolean;
+    }
+  | { readonly kind: 'not-module'; readonly pkg: string }
+  | { readonly kind: 'unknown'; readonly pkg: string };
+
+export interface ProfileModule {
+  readonly pkg: string;
+  readonly unit: string;
+  readonly version: string;
+  readonly registry?: string;
+  readonly local?: boolean;
+}
+
+export interface ProfilePackage {
+  readonly pkg: string;
+  readonly version: string;
+  readonly registry?: string;
+  readonly local?: boolean;
+}
+
+export interface BundleManager {
+  registries(): Promise<BundleRegistries | null>;
+  inspect(spec: string, registry?: BundleRegistry): Promise<BundleInspection | null>;
+  install(request: BundleInstallRequest): Promise<BundleChange | null>;
+  remove(name: string): Promise<BundleChange | null>;
+  setEnabled?(name: string, enabled: boolean): Promise<BundleChange | null>;
+  cancel(requestId: string): Promise<BundleCancellation | null>;
+}
+
+export interface RegistryEntry {
+  readonly scope: string;
+  readonly registry: string;
+}
+
+export interface RegistryNotebook {
+  sources(): readonly RegistryEntry[];
+  remember(entries: readonly RegistryEntry[]): readonly string[];
+}
+
+export interface SelfUpdatePaths {
+  readonly dir: string;
+  readonly script: string;
+  readonly marker: string;
+  readonly log: string;
+}
+
+export interface SelfUpdateRequest {
+  readonly dshHome: string;
+  readonly profile: string;
+  readonly pkg: string;
+  readonly from: string;
+  readonly to: string;
+  readonly pinned: boolean;
+}
+
+export interface SelfUpdateStart {
+  readonly started: boolean;
+  readonly paths: SelfUpdatePaths;
+  readonly forward: string;
+}
+
+export interface OpencliResolution {
+  readonly command: string;
+  readonly source: 'env' | 'isolated' | 'path';
+  readonly isolated: string | null;
+}
+
+export function scopeOf(pkg: string): string | null {
+  const slash = pkg.indexOf('/');
+  return pkg.startsWith('@') && slash > 1 ? pkg.slice(0, slash) : null;
+}
+
+export function normalizeRegistry(url: string): string {
+  const trimmed = url.trim();
+  return trimmed.endsWith('/') ? trimmed : `${trimmed}/`;
+}
+
+export function sameRegistry(a: string | null | undefined, b: string | null | undefined): boolean {
+  if (a === null || a === undefined || b === null || b === undefined) return false;
+  if (a.trim() === '' || b.trim() === '') return false;
+  return normalizeRegistry(a) === normalizeRegistry(b);
+}
+
+export function registryFailure(change: { application?: string; packageResult?: { kind?: string; output?: string }; errorDetail?: string }): boolean {
+  if (change.application !== 'failed') return false;
+  if (change.packageResult?.kind === 'not-found') return true;
+  const output = change.packageResult?.output ?? change.errorDetail ?? '';
+  return /ERR_PNPM_[A-Z_]*FETCH/.test(output);
+}

package/src/host/adapters.ts

@@ -0,0 +1,50 @@
+import type { DshHostContext } from '../api/dsh.js';
+import type { DataReader } from '../contract/data.js';
+import type { LibReader } from '../contract/lib.js';
+import type { GitReader } from '../contract/git.js';
+import type { CommandReader } from '../contract/command.js';
+import type {
+  EnvSupplyPort,
+  HostActions,
+  ModulePort,
+  PluginSurface,
+  ProbePort,
+  ProfilePort,
+  RuntimePort,
+} from './port-types.js';
+
+export const WORKBENCH_ADAPTERS = 'workbenchAdapters';
+
+export const ADAPTER_SET_API_VERSION = 1;
+
+export const SUPPORTED_ADAPTER_API_VERSIONS: readonly number[] = [ADAPTER_SET_API_VERSION];
+
+export interface AdapterSet {
+  readonly apiVersion: number;
+  readonly id: string;
+  readonly version: string;
+  readonly data: DataReader;
+  readonly libs?: LibReader | undefined;
+  readonly git?: GitReader | undefined;
+  readonly commands?: CommandReader | undefined;
+  readonly supply: EnvSupplyPort;
+  readonly modules: ModulePort;
+  readonly profile: ProfilePort;
+  readonly probe: ProbePort;
+  readonly runtime: RuntimePort;
+  readonly plugins: PluginSurface;
+  readonly actions: HostActions;
+}
+
+export type CoreAdapterSet = Pick<
+  AdapterSet,
+  'apiVersion' | 'id' | 'version' | 'data' | 'supply' | 'profile' | 'probe'
+>;
+
+export type WorkbenchAdapters = AdapterSet;
+
+export function adaptersOf(ctx: DshHostContext): AdapterSet {
+  const adapters = ctx.get<AdapterSet>(WORKBENCH_ADAPTERS, false);
+  if (adapters !== undefined) return adapters;
+  throw new Error('workbenchAdapters 未提供');
+}

package/src/host/browser.ts

@@ -0,0 +1,3 @@
+export const BROWSER_SCREEN_SESSION = 'workbench';
+export const BROWSER_READ_SESSION = 'workbench-read';
+export const BROWSER_RECORD_SESSION = 'workbench-rec';

package/src/host/changelog.ts

@@ -0,0 +1,212 @@
+import dayjs from 'dayjs';
+
+export const CHANGELOG_FILE = 'CHANGELOG.md';
+
+export const CHANGELOG_KINDS = ['added', 'changed', 'fixed', 'removed', 'security', 'deprecated'] as const;
+
+export type ChangelogKind = (typeof CHANGELOG_KINDS)[number];
+
+export interface ChangelogSection {
+  readonly version: string;
+  readonly body: string;
+}
+
+export interface ChangelogEntryOptions {
+  readonly version: string;
+  readonly kind?: ChangelogKind | undefined;
+  readonly note: string;
+  readonly date?: string | undefined;
+}
+
+const KIND_LABELS: Readonly<Record<ChangelogKind, string>> = {
+  added: '✨ 新增',
+  changed: '⚡ 改进',
+  fixed: '🐛 修复',
+  removed: '🗑️ 移除',
+  security: '🔒 安全',
+  deprecated: '⚠️ 弃用',
+};
+
+const VERSION_HEADING = /^##[ \t]+\[?v?(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)\]?[ \t]*(?:-[ \t]*.*)?$/;
+const ANY_SECTION = /^##[ \t]/;
+const SUBSECTION = /^###[ \t]/;
+
+export function changelogVersion(value: string): string {
+  return String(value ?? '')
+    .trim()
+    .replace(/^v/, '');
+}
+
+export function changelogDate(now: Date = new Date()): string {
+  return dayjs(now).format('YYYY-MM-DD');
+}
+
+export function normalizeChangelogText(text: string): string {
+  return String(text ?? '').replace(/\r\n?/g, '\n');
+}
+
+function linesOf(text: string): string[] {
+  return normalizeChangelogText(text).split('\n');
+}
+
+function bodyOf(rows: readonly string[]): string {
+  return rows.join('\n').trim();
+}
+
+function sectionRange(
+  rows: readonly string[],
+  version: string,
+): { readonly start: number; readonly end: number } | undefined {
+  const wanted = changelogVersion(version);
+  for (let index = 0; index < rows.length; index += 1) {
+    const row = rows[index] ?? '';
+    if (!ANY_SECTION.test(row)) continue;
+    const match = VERSION_HEADING.exec(row);
+    if (match === null || changelogVersion(match[1] ?? '') !== wanted) continue;
+    let end = rows.length;
+    for (let next = index + 1; next < rows.length; next += 1) {
+      if (ANY_SECTION.test(rows[next] ?? '')) {
+        end = next;
+        break;
+      }
+    }
+    return { start: index, end };
+  }
+  return undefined;
+}
+
+export function changelogSkeleton(): string {
+  return '# 更新日志\n';
+}
+
+export function parseChangelog(text: string): readonly ChangelogSection[] {
+  const rows = linesOf(text);
+  const sections: ChangelogSection[] = [];
+  let current: { readonly version: string; readonly from: number } | undefined;
+  for (let index = 0; index < rows.length; index += 1) {
+    const row = rows[index] ?? '';
+    if (!ANY_SECTION.test(row)) continue;
+    if (current !== undefined) {
+      sections.push({ version: current.version, body: bodyOf(rows.slice(current.from, index)) });
+    }
+    const match = VERSION_HEADING.exec(row);
+    current =
+      match === null
+        ? undefined
+        : { version: changelogVersion(match[1] ?? ''), from: index + 1 };
+  }
+  if (current !== undefined) {
+    sections.push({ version: current.version, body: bodyOf(rows.slice(current.from)) });
+  }
+  return sections;
+}
+
+export function changelogSectionOf(text: string, version: string): string | undefined {
+  const wanted = changelogVersion(version);
+  return parseChangelog(text).find((one) => one.version === wanted)?.body;
+}
+
+export function changelogHasEntry(text: string, version: string): boolean {
+  const body = changelogSectionOf(text, version);
+  if (body === undefined) return false;
+  return body
+    .split('\n')
+    .map((one) => one.trim())
+    .some((one) => one !== '' && !one.startsWith('#') && !one.startsWith('<!--') && !/^`[^`]*`$/.test(one));
+}
+
+function bulletsOf(note: string): string[] {
+  return note
+    .split('\n')
+    .map((one) => one.trim())
+    .filter((one) => one !== '')
+    .map((one) => `- ${one}`);
+}
+
+function blockOf(options: ChangelogEntryOptions, label: string, bullets: readonly string[]): string[] {
+  const date = (options.date ?? '').trim();
+  return [
+    `## v${changelogVersion(options.version)}`,
+    ...(date === '' ? [] : ['', `\`${date}\``]),
+    '',
+    `### ${label}`,
+    '',
+    ...bullets,
+  ];
+}
+
+function insertBlock(rows: readonly string[], at: number, block: readonly string[]): string[] {
+  const before = rows.slice(0, at);
+  while (before.length > 0 && (before[before.length - 1] ?? '').trim() === '') before.pop();
+  const after = rows.slice(at);
+  while (after.length > 0 && (after[0] ?? '').trim() === '') after.shift();
+  const out = [...before];
+  if (out.length > 0) out.push('');
+  out.push(...block);
+  if (after.length > 0) {
+    out.push('');
+    out.push(...after);
+  }
+  return out;
+}
+
+function newSectionAt(rows: readonly string[]): number {
+  for (let index = 0; index < rows.length; index += 1) {
+    if (/^##[ \t]+\[?unreleased\]?[ \t]*$/i.test(rows[index] ?? '')) {
+      for (let next = index + 1; next < rows.length; next += 1) {
+        if (ANY_SECTION.test(rows[next] ?? '')) return next;
+      }
+      return rows.length;
+    }
+  }
+  for (let index = 0; index < rows.length; index += 1) {
+    if (ANY_SECTION.test(rows[index] ?? '')) return index;
+  }
+  return rows.length;
+}
+
+export function appendChangelogEntry(text: string, options: ChangelogEntryOptions): string {
+  const kind: ChangelogKind = options.kind ?? 'changed';
+  const label = KIND_LABELS[kind];
+  const bullets = bulletsOf(options.note);
+  if (bullets.length === 0) return normalizeChangelogText(text);
+  const blocks = blockOf(options, label, bullets);
+  const source = normalizeChangelogText(text).trim() === '' ? changelogSkeleton() : normalizeChangelogText(text);
+  const rows = linesOf(source);
+  const range = sectionRange(rows, options.version);
+  if (range === undefined) return `${insertBlock(rows, newSectionAt(rows), blocks).join('\n').replace(/\n+$/, '')}\n`;
+  let subsection = -1;
+  for (let index = range.start + 1; index < range.end; index += 1) {
+    const heading = (rows[index] ?? '').trim();
+    if (SUBSECTION.test(heading) && heading.includes(label)) {
+      subsection = index;
+      break;
+    }
+  }
+  if (subsection === -1) {
+    const out = [...rows];
+    out.splice(range.end, 0, '', `### ${label}`, '', ...bullets);
+    return `${normalizeWhitespace(out)}\n`;
+  }
+  let end = range.end;
+  for (let index = subsection + 1; index < range.end; index += 1) {
+    if (SUBSECTION.test(rows[index] ?? '')) {
+      end = index;
+      break;
+    }
+  }
+  const out = [...rows];
+  let at = end;
+  while (at > subsection + 1 && (out[at - 1] ?? '').trim() === '') at -= 1;
+  out.splice(at, 0, ...bullets);
+  return `${normalizeWhitespace(out)}\n`;
+}
+
+function normalizeWhitespace(rows: readonly string[]): string {
+  const out: string[] = [];
+  for (const row of rows) {
+    if (row.trim() === '' && out.length > 0 && (out[out.length - 1] ?? '').trim() === '') continue;
+    out.push(row);
+  }
+  return out.join('\n').replace(/\n+$/, '');
+}