@deepseek-ai/dsh-app-boot 0.2.2-alpha.3 → 0.2.2-rc.2

package/src/package-meta.ts

@@ -0,0 +1,200 @@
+/** Read plugin display text and icons through exported resources without evaluating plugin code. */
+
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { dirname, extname, isAbsolute, join, relative, resolve, sep, win32 } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { ModuleLoader } from '@deepseek-ai/cordis-plugin-loader'
+import type { LocalizedText, PluginLocalizedMeta } from '@deepseek-ai/dsh-package-manifest'
+import { barePackageName } from './profile-resolution/resolver.ts'
+import { realModuleFile } from './profile-resolution/legacy-links.ts'
+
+const LANGUAGE_ID = /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/u
+
+type DisplayFields = Record<'title' | 'description', string | undefined>
+
+/** Maximum raw icon bytes admitted to plugin metadata. */
+const MAX_ICON_BYTES = 256 * 1024
+const ICON_MEDIA_TYPES = new Map([
+  ['.svg', 'image/svg+xml'], ['.png', 'image/png'], ['.jpg', 'image/jpeg'],
+  ['.jpeg', 'image/jpeg'], ['.webp', 'image/webp'],
+])
+
+function iconOf(
+  specifier: string, packageName: string, parentURL: string, manifestPath: string | undefined, value: unknown,
+): string | undefined {
+  const icon = manifestPath === undefined ? undefined : textOf(value, `${manifestPath}: icon`)
+  let target: string
+  // Diagnostics name the file the author edits: the declaring manifest or the exported image.
+  let label: string
+  if (manifestPath !== undefined && icon !== undefined) {
+    if (isAbsolute(icon) || win32.isAbsolute(icon) || /^[A-Za-z][A-Za-z\d+.-]*:/u.test(icon)) {
+      throw new Error(`${manifestPath}: icon must be a relative file path`)
+    }
+    label = manifestPath
+    const root = realpathSync(dirname(manifestPath))
+    target = resolve(root, icon)
+    const local = relative(root, realModuleFile(target))
+    if (local === '..' || local.startsWith(`..${sep}`) || isAbsolute(local)) {
+      throw new Error(`${label}: icon must remain inside its manifest directory`)
+    }
+  } else {
+    const exported = optionalResourcePath(`${specifier}/icon`, parentURL)
+    if (exported === undefined) return undefined
+    target = label = exported
+    assertPackageOwned(realModuleFile(target), packageName)
+  }
+  const mediaType = ICON_MEDIA_TYPES.get(extname(target).toLowerCase())
+  if (mediaType === undefined) throw new Error(`${label}: icon must be SVG, PNG, JPEG, or WebP`)
+  const file = realModuleFile(target)
+  const stat = statSync(file)
+  if (!stat.isFile()) throw new Error(`${label}: icon must be a regular file`)
+  if (stat.size > MAX_ICON_BYTES) throw new Error(`${label}: icon exceeds 256 KiB`)
+  const bytes = readFileSync(file)
+  if (bytes.length > MAX_ICON_BYTES) throw new Error(`${label}: icon exceeds 256 KiB`)
+  return `data:${mediaType};base64,${bytes.toString('base64')}`
+}
+
+/** Require an ancestor of the real file whose package.json names the owning package. */
+function assertPackageOwned(file: string, name: string): void {
+  for (let directory = dirname(file); ; directory = dirname(directory)) {
+    const manifest = join(directory, 'package.json')
+    if (existsSync(manifest) && readObject(manifest).name === name) return
+    if (dirname(directory) === directory) throw new Error(`${file}: icon must remain inside its package directory`)
+  }
+}
+
+/**
+ * Resolve a plugin resource through the active Node ESM resolver without evaluating it.
+ * @param specifier - plugin module or exported resource specifier.
+ * @param parentURL - owning module-resolution base.
+ * @returns the local filesystem path selected by Node and the active profile.
+ * @throws when the resolver is unavailable or the resource cannot resolve to a local file.
+ */
+export function resolvePluginResource(specifier: string, parentURL: string): string {
+  const loader = ModuleLoader.fromInternal()
+  if (loader === undefined) throw new Error('Plugin metadata requires the Node module resolver')
+  const result = loader.version === 'v2'
+    ? loader.resolveSync(parentURL, { specifier, attributes: {} })
+    : loader.resolveSync(specifier, parentURL, {})
+  return fileURLToPath(result.url)
+}
+
+function missingResource(error: unknown): boolean {
+  const code = (error as NodeJS.ErrnoException | null)?.code
+  return code === 'ERR_PACKAGE_PATH_NOT_EXPORTED' || code === 'ERR_MODULE_NOT_FOUND'
+    || code === 'MODULE_NOT_FOUND' || code === 'ENOENT' || code === 'ENOTDIR'
+}
+
+function optionalResourcePath(specifier: string, parentURL: string): string | undefined {
+  try {
+    return resolvePluginResource(specifier, parentURL)
+  } catch (error) {
+    if (missingResource(error)) return undefined
+    throw error
+  }
+}
+
+function objectOf(value: unknown, path: string): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`${path} must be an object`)
+  }
+  return value as Record<string, unknown>
+}
+
+function textOf(value: unknown, path: string): string | undefined {
+  if (value === undefined) return undefined
+  if (typeof value !== 'string' || value.trim() === '') throw new Error(`${path} must be a non-empty string`)
+  return value
+}
+
+function readObject(file: string): Record<string, unknown> {
+  let contents: unknown
+  try {
+    contents = JSON.parse(readFileSync(file, 'utf8'))
+  } catch (error) {
+    throw new Error(`${file}: ${String(error)}`)
+  }
+  return objectOf(contents, file)
+}
+
+function fallbackText(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() !== '' ? value : undefined
+}
+
+function dictionariesOf(englishPath: string, specifier: string, parentURL: string): Map<string, DisplayFields> {
+  const dictionaries = new Map<string, DisplayFields>()
+  for (const entry of readdirSync(dirname(englishPath), { withFileTypes: true })) {
+    if (!entry.name.endsWith('.json')) continue
+    const resource = `${specifier}/locale/${entry.name}`
+    const language = entry.name.slice(0, -5)
+    if (!LANGUAGE_ID.test(language)) throw new Error(`${resource} must use a language id as its filename`)
+    const id = language.toLowerCase()
+    if (dictionaries.has(id)) throw new Error(`${resource} duplicates locale ${id}`)
+    const file = resolvePluginResource(resource, parentURL)
+    if (dirname(file) !== dirname(englishPath)) {
+      throw new Error(`${resource}: ${file} must share the English locale directory ${dirname(englishPath)}`)
+    }
+    const parsed = readObject(file)
+    const meta = parsed.meta === undefined ? undefined : objectOf(parsed.meta, `${file}: meta`)
+    dictionaries.set(id, {
+      title: textOf(meta?.title, `${file}: meta.title`),
+      description: textOf(meta?.description, `${file}: meta.description`),
+    })
+  }
+  return dictionaries
+}
+
+function localizedText(
+  field: keyof DisplayFields, dictionaries: Map<string, DisplayFields>, fallback: string | undefined, finalFallback: string,
+): LocalizedText | undefined {
+  const entries = [...dictionaries].flatMap(([language, fields]): [string, string][] => {
+    const value = fields[field]
+    return value === undefined ? [] : [[language, value]]
+  })
+  if (entries.length === 0) return fallback
+  return { en: fallback ?? finalFallback, ...Object.fromEntries(entries) }
+}
+
+/**
+ * Read plugin locale JSON display text and icon without evaluating JavaScript entries.
+ * Only a package-root specifier reads its exported package.json: `name`/`description` fill missing
+ * locale fields, and a declared `icon` takes priority over the `<specifier>/icon` resource.
+ * A subpath specifier never reads package.json; its icon comes only from `<specifier>/icon`.
+ * Manifest icons remain inside their declaring directory; exported icons remain inside their
+ * owning package after realpath resolution. Both accept SVG, PNG, JPEG, or WebP up to 256 KiB.
+ * Icon failures retain display text without falling back.
+ * Non-package specifiers are skipped without invoking the resource resolver.
+ * Language files share the directory containing the resolved English resource;
+ * each file is resolved through the complete plugin specifier before reading.
+ * Translation maps retain an English fallback, ultimately the full module specifier
+ * for titles and empty for descriptions.
+ * @param specifier - configured plugin module name, including any package subpath.
+ * @param parentURL - owning Loader tree's module-resolution base.
+ * @returns display fields and any resource diagnostic, or undefined for non-package specifiers or absent metadata.
+ */
+export function readPluginMeta(specifier: string, parentURL: string): PluginLocalizedMeta | undefined {
+  const packageName = barePackageName(specifier)
+  if (packageName === undefined) return undefined
+  try {
+    const englishPath = optionalResourcePath(`${specifier}/locale/en.json`, parentURL)
+    const dictionaries = englishPath === undefined ? new Map<string, DisplayFields>() : dictionariesOf(englishPath, specifier, parentURL)
+    const manifestPath = packageName === specifier ? optionalResourcePath(`${specifier}/package.json`, parentURL) : undefined
+    const manifest = manifestPath === undefined ? undefined : readObject(manifestPath)
+    const title = localizedText('title', dictionaries, fallbackText(manifest?.name), specifier)
+    const description = localizedText('description', dictionaries, fallbackText(manifest?.description), '')
+    const text = {
+      ...title === undefined ? {} : { title },
+      ...description === undefined ? {} : { description },
+    }
+    let icon: string | undefined
+    try {
+      icon = iconOf(specifier, packageName, parentURL, manifestPath, manifest?.icon)
+    } catch (error) {
+      return { ...text, error: `Plugin metadata for ${specifier}: ${String(error)}` }
+    }
+    if (title === undefined && description === undefined && icon === undefined) return undefined
+    return { ...text, ...icon === undefined ? {} : { icon } }
+  } catch (error) {
+    return { error: `Plugin metadata for ${specifier}: ${String(error)}` }
+  }
+}

package/src/plugin-compatibility.ts

@@ -0,0 +1,117 @@
+/** Evaluate plugin dsh requirements (`engines.dsh`, else dsh peers) without importing plugin code. */
+
+import fs from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import semver from 'semver'
+
+/** Unmet dsh requirements and the exact plugin/runtime exemption decision. */
+export interface PluginCompatibility {
+  name: string
+  version: string
+  runtimeVersion: string
+  /** Only requirements the running dsh version does not satisfy: `engines.dsh`, or dsh peer package names. */
+  requirements: Record<string, string>
+  exempted: boolean
+}
+
+function objectOf(value: unknown, field: string): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`${field} must be an object`)
+  }
+  return value as Record<string, unknown>
+}
+
+function runtimeVersionOf(value: unknown): string {
+  if (typeof value !== 'string' || semver.valid(value) === null) {
+    throw new Error(`Invalid dsh runtime version: ${JSON.stringify(value)}; expected a semantic version`)
+  }
+  return value
+}
+
+function identityField(manifest: Record<string, unknown>, field: 'name' | 'version'): string {
+  const value = Object.hasOwn(manifest, field) ? manifest[field] : undefined
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`Plugin manifest ${field} must be a non-empty string when dsh requirements are unmet`)
+  }
+  return value
+}
+
+/**
+ * Read this app-boot package's version in both source and bundled installations.
+ * @returns the validated runtime semantic version, preserving its exact spelling.
+ * @throws if package.json cannot be read or its version is missing or invalid.
+ */
+export function getDshRuntimeVersion(): string {
+  // The executable's virtual filesystem intercepts string paths, not URL arguments.
+  const filename = fileURLToPath(new URL('../package.json', import.meta.url))
+  const manifest = objectOf(JSON.parse(fs.readFileSync(filename, 'utf8')), 'app-boot package.json')
+  return runtimeVersionOf(Object.hasOwn(manifest, 'version') ? manifest.version : undefined)
+}
+
+function satisfies(runtimeVersion: string, range: string): boolean {
+  return range.trim() !== '' && semver.satisfies(runtimeVersion, range, { includePrerelease: true })
+}
+
+function unmetRequirements(fields: Record<string, unknown>, runtimeVersion: string): Record<string, string> {
+  const engines = Object.hasOwn(fields, 'engines') ? objectOf(fields.engines, 'Plugin manifest engines') : {}
+  if (Object.hasOwn(engines, 'dsh')) {
+    const range = engines.dsh
+    if (typeof range !== 'string') throw new Error('Plugin manifest engines.dsh must be a string')
+    return satisfies(runtimeVersion, range) ? {} : { 'engines.dsh': range }
+  }
+  if (!Object.hasOwn(fields, 'peerDependencies')) return {}
+  const dependencies = objectOf(fields.peerDependencies, 'Plugin manifest peerDependencies')
+  const unmet: Record<string, string> = {}
+  for (const [name, range] of Object.entries(dependencies)) {
+    if (typeof range !== 'string') {
+      throw new Error(`Plugin manifest peerDependencies[${JSON.stringify(name)}] must be a string`)
+    }
+    if (name !== '@deepseek-ai/dsh' && !name.startsWith('@deepseek-ai/dsh-')) continue
+    const requirement = ['workspace:^', 'workspace:~', 'workspace:*'].includes(range) ? runtimeVersion : range
+    if (!satisfies(runtimeVersion, requirement)) unmet[name] = range
+  }
+  return unmet
+}
+
+/**
+ * Check the plugin's dsh requirements against the runtime. An own `engines.dsh` range decides alone and
+ * peerDependencies are ignored; otherwise every @deepseek-ai/dsh or @deepseek-ai/dsh-* peer must match.
+ * Prereleases participate in ranges. For peers only, workspace:^, workspace:~, and workspace:* refer to
+ * the current runtime; other empty or invalid ranges, including any workspace: `engines.dsh`, are unmet.
+ * @param manifest - parsed plugin package.json; inherited fields are ignored.
+ * @param exemptions - exact plugin name@version keys mapped to exact runtime versions.
+ * @param runtimeVersion - running dsh version, defaulting to this app-boot package.
+ * @returns unmet requirements and exemption status, or undefined when every requirement is met.
+ * @throws for malformed manifest engines or peer fields, invalid runtime versions, or missing identity on a mismatch.
+ */
+export function evaluatePluginCompatibility(
+  manifest: object,
+  exemptions: Readonly<Record<string, readonly string[]>> = {},
+  runtimeVersion = getDshRuntimeVersion(),
+): PluginCompatibility | undefined {
+  runtimeVersionOf(runtimeVersion)
+  const fields = objectOf(manifest, 'Plugin manifest')
+  const requirements = unmetRequirements(fields, runtimeVersion)
+  if (Object.keys(requirements).length === 0) return undefined
+  const name = identityField(fields, 'name')
+  const version = identityField(fields, 'version')
+  const key = `${name}@${version}`
+  const exemptedVersions = Object.hasOwn(exemptions, key) ? exemptions[key] : undefined
+  const exempted = exemptedVersions?.includes(runtimeVersion) === true
+  return { name, version, runtimeVersion, requirements, exempted }
+}
+
+/**
+ * Describe unmet requirements, their risk, and the exact-version remedy.
+ * Surfaces with their own grant mechanism or locale render the structured result themselves.
+ * @param issue - incompatible plugin/runtime result, including exempted mismatches.
+ * @returns an English diagnostic for logs and stderr.
+ */
+export function pluginCompatibilityWarning(issue: PluginCompatibility): string {
+  const key = `${issue.name}@${issue.version}`
+  return `Plugin ${key} is incompatible with dsh ${issue.runtimeVersion}: requirements ${JSON.stringify(issue.requirements)}. `
+    + 'Running it may cause crashes or data loss. '
+    + 'Update the plugin or install a plugin version compatible with this dsh runtime. '
+    + `To accept this risk explicitly, grant the exact-version exemption for ${key} on dsh ${issue.runtimeVersion} with \`dsh plugin allow-version\` or the plugin manager, then retry the installation or restart dsh. `
+    + `Exact-version exemption: ${issue.exempted ? 'active' : 'not active'}.`
+}

package/src/profile-compatibility.ts

@@ -0,0 +1,141 @@
+/** Profile-local compatibility permissions readable before any Cordis plugins load. */
+import { readFileSync } from 'node:fs'
+import { mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { parse } from 'semver'
+import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
+import { getDshRuntimeVersion } from './plugin-compatibility.ts'
+
+/** Independent profile metadata; neither package manifests nor Cordis patches carry grants. */
+export const PROFILE_COMPATIBILITY_FILENAME = 'compatibility.json'
+
+/** Published and scoped npm package names, as npm accepts them in a manifest dependency key. */
+const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/
+
+/** Whether a decoded record accepts only exact DSH versions. */
+function isVersionList(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every(version => typeof version === 'string' && isExactPluginVersion(version))
+}
+
+/** Test whether an exemption names a canonical exact SemVer, including build metadata.
+ * @param value Version supplied by a manifest or user.
+ * @returns False for ranges, prefixes, whitespace, and malformed versions.
+ */
+export function isExactPluginVersion(value: string): boolean {
+  const parsed = parse(value)
+  return parsed !== null && value === `${parsed.version}${parsed.build.length === 0 ? '' : `+${parsed.build.join('.')}`}`
+}
+
+/** Validate one explicit exemption without granting it.
+ * @param packageVersion Exact npm package-name@version, never an installation spec or range.
+ * @param runtimeVersion Exact DSH version, including prerelease and build metadata.
+ * @throws When either identity is not canonical.
+ */
+export function validatePluginVersionExemption(packageVersion: string, runtimeVersion: string): void {
+  const separator = packageVersion.lastIndexOf('@')
+  if (separator <= 0 || !PACKAGE_NAME.test(packageVersion.slice(0, separator))
+    || !isExactPluginVersion(packageVersion.slice(separator + 1)) || !isExactPluginVersion(runtimeVersion)) {
+    throw new Error('Version exemptions require an exact npm package-name@version and an exact DSH runtime version')
+  }
+}
+
+/** What one profile's compatibility file currently authorizes, and what is wrong with it. */
+export interface ProfileCompatibility {
+  /** Accepted exact package-name@version keys mapped to their allowed DSH versions. */
+  readonly exemptions: Record<string, string[]>
+  /** Human-readable problems; empty when every record was accepted. */
+  readonly warnings: string[]
+  /**
+   * Whether the file holds nothing this reader rejected, so a grant or revocation may rewrite it.
+   * A false value means writing would discard content the user must repair by hand.
+   */
+  readonly rewritable: boolean
+}
+
+/** Read the profile's independent compatibility file without loading plugins.
+ * A missing file authorizes nothing. An unreadable or unparsable file authorizes nothing and is
+ * reported instead of failing, so a bad file can never make the profile unusable; rejected records
+ * are skipped while the remaining valid ones still apply.
+ * @param profileDir Absolute profile directory.
+ * @returns Accepted exemptions plus every problem found; no manifest fallback is used.
+ */
+export function readProfileCompatibility(profileDir: string): ProfileCompatibility {
+  const filename = join(profileDir, PROFILE_COMPATIBILITY_FILENAME)
+  const unreadable = (reason: string): ProfileCompatibility =>
+    ({ exemptions: {}, warnings: [`${filename} ${reason}; treating the profile as having no exemptions`], rewritable: false })
+  let text: string
+  try { text = readFileSync(filename, 'utf8') }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { exemptions: {}, warnings: [], rewritable: true }
+    return unreadable(`cannot be read (${String(error)})`)
+  }
+  let value: unknown
+  try { value = JSON.parse(text) }
+  catch (error) { return unreadable(`is not valid JSON (${String(error)})`) }
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return unreadable('must map exact package@version keys to DSH version lists')
+  }
+  const exemptions: Record<string, string[]> = {}
+  const warnings: string[] = []
+  for (const [key, versions] of Object.entries(value as Record<string, unknown>)) {
+    const separator = key.lastIndexOf('@')
+    if (separator <= 0 || !PACKAGE_NAME.test(key.slice(0, separator)) || !isExactPluginVersion(key.slice(separator + 1))) {
+      warnings.push(`${filename}: ${JSON.stringify(key)} is not an exact package-name@version key; the record is ignored`)
+      continue
+    }
+    if (!isVersionList(versions)) {
+      warnings.push(`${filename}: ${key} must contain a list of exact DSH versions; the record is ignored`)
+      continue
+    }
+    exemptions[key] = versions
+  }
+  return { exemptions, warnings, rewritable: warnings.length === 0 }
+}
+
+/** Read only the accepted exemptions of a profile.
+ * @param profileDir Absolute profile directory.
+ * @returns Exact package-name@version keys mapped to their allowed DSH versions.
+ */
+export function readProfileVersionExemptions(profileDir: string): Record<string, string[]> {
+  return readProfileCompatibility(profileDir).exemptions
+}
+
+/** Persist one informed grant or revocation under the compatibility file's own lock.
+ * @param profileDir Profile directory; no package manifest is created or modified.
+ * @param packageVersion Exact manifest package-name@version.
+ * @param runtimeVersion Exact DSH version; grants must name the current runtime, revocations may name historical ones.
+ * @param enabled Whether to grant rather than revoke.
+ * @param acceptRisk Required true for grants after explicit acknowledgement of possible crashes or data loss.
+ * @returns After the atomic write. Existing plugin instances are not reloaded by this operation.
+ * @throws For invalid identities, missing consent, a stale runtime, or a file the reader rejected,
+ * which the user must repair by hand because rewriting it would discard their content.
+ */
+export async function setProfileVersionExemption(
+  profileDir: string, packageVersion: string, runtimeVersion: string, enabled: boolean, acceptRisk: boolean,
+): Promise<void> {
+  validatePluginVersionExemption(packageVersion, runtimeVersion)
+  if (enabled && !acceptRisk) {
+    throw new Error('Incompatible plugins may cause crashes or data loss. To grant this exact-version exemption, explicitly acknowledge the risk with --accept-risk (acceptRisk: true).')
+  }
+  const current = getDshRuntimeVersion()
+  if (enabled && runtimeVersion !== current) {
+    throw new Error(`Cannot approve DSH ${runtimeVersion}: this application runs DSH ${current}. Use --dsh-version ${current}.`)
+  }
+  await mkdir(profileDir, { recursive: true })
+  const filename = join(profileDir, PROFILE_COMPATIBILITY_FILENAME)
+  await withFileLock(filename, async () => {
+    const current = readProfileCompatibility(profileDir)
+    if (!current.rewritable) {
+      throw new Error(`${PROFILE_COMPATIBILITY_FILENAME} must be repaired before exemptions change:\n${current.warnings.join('\n')}`)
+    }
+    const exemptions = current.exemptions
+    const versions = exemptions[packageVersion] ?? []
+    if (enabled) exemptions[packageVersion] = [...new Set([...versions, runtimeVersion])]
+    else {
+      const retained = versions.filter(version => version !== runtimeVersion)
+      if (retained.length) exemptions[packageVersion] = retained
+      else Reflect.deleteProperty(exemptions, packageVersion)
+    }
+    await writeFileAtomic(filename, JSON.stringify(exemptions, undefined, 2) + '\n', { mode: 0o600 })
+  })
+}

package/src/profile-context.ts

@@ -0,0 +1,85 @@
+/** Launcher-owned profile locations and composition inputs. */
+import { join } from 'node:path'
+import { composeEntries, loadProfileDirectory, PROFILE_PATCH_FILENAME, type Profile } from './profile.ts'
+import { loadOptionalPatches } from './index.ts'
+import type { PatchOptions } from '@deepseek-ai/cordis-plugin-include'
+
+/** Application-owned package manager executable; environment applies only to package operations. */
+export interface ProfilePnpmInvocation {
+  readonly command: string
+  readonly args: readonly string[]
+  readonly env: Readonly<Record<string, string>>
+}
+
+/** Current profile facts; scheduling and mutation belong to their callers. */
+export interface ProfileContext {
+  readonly name: string
+  /** Packaged applications supply their bundled runtime instead of a PATH executable. */
+  readonly packageManager?: ProfilePnpmInvocation
+  readonly dir: string
+  readonly patchPath: string
+  readonly installAnchor: string
+  readonly cwd: string
+  readonly home: string
+  /** Bundle packages used to start this process, before any persisted edits. */
+  readonly startedBundles: readonly string[]
+  /** Parsed command-line overlays, applied above profile and home patches. */
+  readonly overlays: readonly PatchOptions[]
+  /** Launch-time DSH_TELEMETRY_DISABLED value; any non-empty value opts out. */
+  readonly telemetryDisabledEnv: string | undefined
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** Present only in a profile launched by dsh. */
+    profileContext: ProfileContext
+  }
+}
+
+const TELEMETRY_ROW_ID = 'session-telemetry-otel'
+
+/**
+ * Resolve the telemetry opt-out switch into its boot patch. ANY non-empty
+ * value (including `'0'`/`'false'`) disables: a privacy switch prefers
+ * off-by-mistake over on-by-mistake. A composition without the telemetry row
+ * exports nothing, so the switch is then trivially satisfied and no patch is
+ * generated — custom profiles need not mount telemetry to run with the
+ * switch set.
+ * @param disabledEnv - the raw `DSH_TELEMETRY_DISABLED` value (`undefined` when unset).
+ * @param hasRow - whether the composition carries the telemetry row.
+ * @returns the disable patch, or `undefined` when no hard-disable patch is required.
+ */
+export function resolveTelemetryPatch(disabledEnv: string | undefined, hasRow: boolean): PatchOptions | undefined {
+  if ((disabledEnv ?? '') === '' || !hasRow) return undefined
+  return { id: TELEMETRY_ROW_ID, disabled: true }
+}
+
+/** Read the selected bundles' patches, which apply before the profile patch file.
+ * @param binName Diagnostic prefix for malformed or missing configuration.
+ * @param context Data supplied by the profile launcher.
+ * @param initialProfile Already loaded startup profile; omitted reads the current files.
+ * @returns Bundle patches in application order.
+ */
+export function readBundlePatches(binName: string, context: ProfileContext, initialProfile?: Profile): PatchOptions[] {
+  const profile = initialProfile ?? loadProfileDirectory(binName, context.dir, context.installAnchor, { userLayer: false })
+  return profile.layers.flatMap(layer => layer.patches)
+}
+
+/** Read current bundle and user layers with the launch-time overlays.
+ * @param binName Diagnostic prefix for malformed or missing configuration.
+ * @param context Data supplied by the profile launcher.
+ * @param initialProfile Already loaded startup profile; omitted reads the current files.
+ * @returns Detached ordered patches; this function does not update the Loader.
+ */
+export function readProfilePatches(binName: string, context: ProfileContext, initialProfile?: Profile): PatchOptions[] {
+  const patches = structuredClone([
+    ...readBundlePatches(binName, context, initialProfile),
+    ...(initialProfile?.patches ?? loadOptionalPatches(binName, context.patchPath) ?? []),
+    ...(loadOptionalPatches(binName, join(context.home, PROFILE_PATCH_FILENAME)) ?? []),
+    ...context.overlays,
+  ])
+  const telemetryPatch = resolveTelemetryPatch(context.telemetryDisabledEnv,
+    composeEntries([patches]).some(row => row.id === TELEMETRY_ROW_ID))
+  if (telemetryPatch !== undefined) patches.push(telemetryPatch)
+  return patches
+}