Merge remote-tracking branch 'origin/master' into fix/checkout-workdir-prompt

# Conflicts: # packages/ui/app-boot/README.i18n.yaml # packages/ui/app-boot/README.md # packages/ui/app-boot/README.zh.md
2026-08-01 00:02:17 +08:00
parent f6ab04e486 992fdc0cee
commit cb1a6c74dc
1843 changed files with 146944 additions and 15125 deletions
@@ -1,8 +1,8 @@
 /**
 * Shared boot glue for the app bins (`dsh`, `dsh-cli-demo`, `dsh-acp-demo`): load the gitignored
 * `.env`, install the fail-loud Loader guards, resolve the config path (snapshot-aware), load the
- * optional personal overlay patches from the Harness home (`~/.dsh`), and drive the cordis Loader
- * against a leaf `cordis.yml` until the whole tree has settled.
+ * optional personal overlay patches from the Harness home (`~/.dsh`), expose its path resolver to
+ * config expressions, and drive the Cordis Loader against a leaf `cordis.yml` until the tree settles.
 * @module @deepseek-ai/dsh-app-boot
 */

@@ -10,13 +10,20 @@ import { pathToFileURL } from 'node:url'
 import { readFileSync } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
 import * as yaml from 'js-yaml'
-import { Context } from 'cordis'
+import { Context, type FiberState } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
-import Include, { type PatchOptions } from '@cordisjs/plugin-include'
-import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import Include, { applyEntryPatches, entryListSchema, type PatchOptions } from '@cordisjs/plugin-include'
+import { dshHomePath, resolveDshHome } from '@deepseek-ai/dsh-paths'
 // Side-effect type import: resolves `ctx.get('systemPrompt')` to the service.
 import type {} from '@deepseek-ai/dsh-system-prompt'

+declare module 'cordis' {
+  interface Context {
+    /** Harness-home path resolver available to Loader `!!js` config expressions. */
+    dshHomePath?: typeof dshHomePath
+  }
+}
+
 /**
 * Resolve the config to boot. Replay swaps a `cordis.yml` basename for
 * `cordis.snapshot.yml` in the same directory; every other mode keeps the path.
@@ -60,16 +67,12 @@ export function loadEnv(
 /** File inside the Harness home holding the personal loader overlay patches. */
 export const PERSONAL_CONFIG_FILENAME = 'config.yaml'

-// The include's YAML dialect: `!!js` scalars become expression nodes the
-// Loader interpolates against each entry's context at mount time. Personal
-// patches are parsed with the same schema so they may reference `process.env`.
-// Load-only: this schema never dumps, so no `predicate`/`represent`.
-const jsExprType = new yaml.Type('tag:yaml.org,2002:js', {
-  kind: 'scalar',
-  resolve: data => typeof data === 'string',
-  construct: data => ({ __jsExpr: String(data) }),
-})
-const personalPatchesSchema = yaml.JSON_SCHEMA.extend(jsExprType)
+// The include's YAML dialect (`!!js` scalars become expression nodes the
+// Loader interpolates against each entry's context at mount time), imported
+// from the include itself so patch parsing and config dumping can never drift
+// from what the include mounts. Personal patches share it so they may
+// reference `process.env`.
+const personalPatchesSchema = entryListSchema

 /**
 * Load the optional personal overlay patches (`config.yaml` under the Harness
@@ -94,25 +97,196 @@ export function loadPersonalPatches(
    if ((error as NodeJS.ErrnoException | null)?.code === 'ENOENT') return undefined
    throw new Error(`${binName}: failed to read personal patches ${file}: ${String(error)}`)
  }
+  return parsePatchList(binName, file, content, 'personal patches')
+}
+
+/**
+ * Load a required overlay patch list: a surface overlay (`tui.cordis.yml`) or a
+ * `--config <path>` overlay applied over the shared base. Same file format as
+ * {@link loadPersonalPatches}, but a missing file throws, because the caller
+ * named this file — its absence is a misconfiguration, not "no overlay".
+ * @param binName - the diagnostic prefix on the thrown error.
+ * @param file - absolute path of the overlay file.
+ * @returns the parsed patch list.
+ */
+export function loadOverlayPatches(binName: string, file: string): PatchOptions[] {
+  let content: string
+  try {
+    content = readFileSync(file, 'utf8')
+  } catch (error) {
+    throw new Error(`${binName}: failed to read overlay ${file}: ${String(error)}`)
+  }
+  return parsePatchList(binName, file, content, 'overlay')
+}
+
+/**
+ * Parse one loader patch list: a top-level YAML array of
+ * `@cordisjs/plugin-include` `PatchOptions` (id-targeted config overrides and
+ * `insert` lists, `!!js` expressions allowed). Every shape failure throws,
+ * because a patch file that cannot be applied at all is a misconfiguration; a
+ * single patch whose target row is absent stays a per-entry Loader warning, so
+ * one overlay shared across surfaces does not have to match every tree.
+ * @param binName - the diagnostic prefix on the thrown error.
+ * @param file - the source path, quoted in errors.
+ * @param content - the file's text.
+ * @param label - what to call this list in errors (`personal patches`, `overlay`).
+ * @returns the parsed patch list.
+ */
+function parsePatchList(
+  binName: string, file: string, content: string, label: string,
+): PatchOptions[] {
  let parsed: unknown
  try {
    parsed = yaml.load(content, { schema: personalPatchesSchema })
  } catch (error) {
-    throw new Error(`${binName}: failed to parse personal patches ${file}: ${String(error)}`)
+    throw new Error(`${binName}: failed to parse ${label} ${file}: ${String(error)}`)
  }
  if (!Array.isArray(parsed)) {
-    throw new Error(`${binName}: personal patches ${file} must be a top-level YAML array of loader patch entries`)
+    throw new Error(`${binName}: ${label} ${file} must be a top-level YAML array of loader patch entries`)
  }
-  // A present personal config that cannot apply is a misconfiguration and must
-  // fail loud here — the include only warns per entry at mount.
  parsed.forEach((entry, index) => {
    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
-      throw new Error(`${binName}: personal patches entry ${index + 1} in ${file} must be a mapping (a loader patch entry)`)
+      throw new Error(`${binName}: ${label} entry ${index + 1} in ${file} must be a mapping (a loader patch entry)`)
    }
  })
  return parsed as PatchOptions[]
 }

+/** One overlay patch list with the label provenance comments print for it. */
+export interface ConfigDumpLayer {
+  /** Source name shown in provenance comments (a file basename or path). */
+  label: string
+  /** The layer's patches, from {@link loadOverlayPatches} / {@link loadPersonalPatches}. */
+  patches: PatchOptions[]
+}
+
+/**
+ * Compose the effective entry list exactly as `boot()` would mount it: parse
+ * the base config file with the include's entry-list dialect, apply every
+ * layer's patches as ONE flattened list through the include's own patch
+ * algorithm (`applyEntryPatches`) — the same single call `boot()` makes, so
+ * even patch-visibility corner cases (a later layer targeting a group child a
+ * plain config replacement introduced, which the single-pass id index never
+ * sees) compose identically — then render the result as YAML in the same
+ * dialect (`!!js` expressions print verbatim, unevaluated).
+ *
+ * Every run of rows with the same provenance is preceded by a `# ==` comment
+ * naming the file that contributed the rows and any layers that patched them,
+ * so the output stays a loadable YAML document while showing which section
+ * comes from which file. Provenance is derived from single-call prefix
+ * snapshots (base + layers 1..k), diffed positionally: the patch algorithm
+ * only rewrites rows in place or appends, so a top-level index identifies one
+ * row across snapshots, and a layer whose addition changes the row (config
+ * replacement, disable, group insert) is listed as having patched it.
+ *
+ * A patch that matches no row is reported through `warn` with its layer
+ * label, mirroring the Loader's boot-time warning. Earlier layers' patches
+ * see an identical preceding state in every snapshot that includes them, so
+ * each snapshot's warning list extends the previous one and the new tail
+ * belongs to the added layer.
+ * @param binName - the diagnostic prefix on read/parse errors.
+ * @param absoluteConfigPath - the base config file `boot()` would include.
+ * @param layers - overlay layers in application order (later wins).
+ * @param warn - sink for skipped-patch diagnostics; defaults to stderr.
+ * @returns the composed entry list rendered as a YAML document with
+ * provenance comment separators.
+ */
+export function renderConfigDump(
+  binName: string,
+  absoluteConfigPath: string,
+  layers: ConfigDumpLayer[],
+  warn: (line: string) => void = line => void process.stderr.write(`${line}\n`),
+): string {
+  let content: string
+  try {
+    content = readFileSync(absoluteConfigPath, 'utf8')
+  } catch (error) {
+    throw new Error(`${binName}: failed to read config ${absoluteConfigPath}: ${String(error)}`)
+  }
+  let parsed: unknown
+  try {
+    parsed = yaml.load(content, { schema: entryListSchema })
+  } catch (error) {
+    throw new Error(`${binName}: failed to parse config ${absoluteConfigPath}: ${String(error)}`)
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error(`${binName}: config ${absoluteConfigPath} must be a top-level YAML array of entries`)
+  }
+  const baseLabel = basename(absoluteConfigPath)
+  // The YAML boundary yields untyped rows; the include validates entry shape
+  // at mount, and the dump prints whatever the file holds, so `EntryOptions`
+  // here is structural trust in the same file `boot()` would include.
+  const base = parsed as Parameters<typeof applyEntryPatches>[0]
+  // snapshot_k = ONE application of layers 1..k flattened — boot's exact call
+  // shape for that prefix. snapshot_N is therefore the mounted composition.
+  // The patches are cloned per call: applyEntryPatches detaches the entry
+  // list but pushes `insert` rows by reference from the patch list, so
+  // sharing patch objects across snapshot calls would leak a later
+  // snapshot's mutations into an earlier one's result.
+  const snapshot = (count: number, warnings: string[]): ReturnType<typeof applyEntryPatches> => {
+    const flattened = structuredClone(layers.slice(0, count).flatMap(layer => layer.patches))
+    return applyEntryPatches(base, flattened, (message: string, ...args: unknown[]) => {
+      // The include logs through cordis's printf-style logger (`%C` = code); a
+      // dump has no logger, so substitute inline for a plain line.
+      let index = 0
+      warnings.push(message.replace(/%C/g, () => JSON.stringify(args[index++])))
+    })
+  }
+  let previous = base
+  let previousWarnings: string[] = []
+  const provenance: { origin: string; patchedBy: string[] }[] = base.map(() => ({ origin: baseLabel, patchedBy: [] }))
+  let composed = base
+  for (let count = 1; count <= layers.length; count += 1) {
+    const layer = layers[count - 1]
+    /* v8 ignore next -- count iterates 1..length, so the slot exists */
+    if (layer === undefined) continue
+    const warnings: string[] = []
+    composed = snapshot(count, warnings)
+    for (const line of warnings.slice(previousWarnings.length)) {
+      warn(`${binName}: [${layer.label}] ${line}`)
+    }
+    const before = previous.map(entry => JSON.stringify(entry))
+    for (let index = 0; index < composed.length; index += 1) {
+      if (index >= before.length) provenance.push({ origin: layer.label, patchedBy: [] })
+      else if (JSON.stringify(composed[index]) !== before[index]) provenance[index]?.patchedBy.push(layer.label)
+    }
+    previous = composed
+    previousWarnings = warnings
+  }
+  return groupedDump(composed, provenance)
+}
+
+/** Render the composed rows grouped under one provenance comment per contiguous run. */
+function groupedDump(
+  composed: readonly unknown[],
+  provenance: readonly { origin: string; patchedBy: string[] }[],
+): string {
+  const lines: string[] = []
+  let currentLabel: string | undefined
+  let group: unknown[] = []
+  const flush = (): void => {
+    if (currentLabel === undefined || group.length === 0) return
+    lines.push(`# == ${currentLabel}`)
+    lines.push(yaml.dump(group, { schema: entryListSchema, noRefs: true }).trimEnd())
+    group = []
+  }
+  for (let index = 0; index < composed.length; index += 1) {
+    const record = provenance[index]
+    /* v8 ignore next -- provenance is index-aligned with composed by construction */
+    if (record === undefined) continue
+    const label = record.patchedBy.length === 0
+      ? record.origin
+      : `${record.origin}, patched by ${record.patchedBy.join(', ')}`
+    if (label !== currentLabel) {
+      flush()
+      currentLabel = label
+    }
+    group.push(composed[index])
+  }
+  flush()
+  return lines.join('\n') + '\n'
+}
+
 /**
 * The slice of `process` {@link installFailLoud} needs — injectable so tests
 * exercise the handler without registering on (or exiting) the real process.
@@ -124,16 +298,46 @@ export interface FailLoudProcess {
  exit(code: number): void
 }

+// Loader rc.5 derives and drops a rejected promise after a fiber fails. Keep
+// exact reasons already folded into the boot diagnostic visible through the
+// next process rejection checkpoint so the process guard can coalesce them.
+const assembledActivationRejections = new Map<unknown, number>()
+
+function retainAssembledRejection(reason: unknown): void {
+  assembledActivationRejections.set(reason, (assembledActivationRejections.get(reason) ?? 0) + 1)
+}
+
+function releaseAssembledRejection(reason: unknown): void {
+  const count = assembledActivationRejections.get(reason)
+  if (count === undefined || count === 1) {
+    assembledActivationRejections.delete(reason)
+  } else {
+    assembledActivationRejections.set(reason, count - 1)
+  }
+}
+
+async function observeLoaderRejectionCheckpoint(reasons: readonly unknown[]): Promise<void> {
+  for (const reason of reasons) retainAssembledRejection(reason)
+  try {
+    await new Promise<void>(resolve => setImmediate(resolve))
+  } finally {
+    for (const reason of reasons) releaseAssembledRejection(reason)
+  }
+}
+
 /**
 * Install before boot to turn a late unhandled plugin-init rejection into one
- * labelled stderr diagnostic and `exit(1)`. Stdout remains untouched for ACP;
- * the returned function removes the handler.
+ * labelled stderr diagnostic and `exit(1)`. A rejection already included by
+ * {@link assertEntriesActivated} is ignored during its process checkpoint;
+ * every other rejection remains fatal. Stdout remains untouched for ACP; the
+ * returned function removes the handler.
 * @param binName - the diagnostic prefix on the fatal-failure line.
 * @param proc - the process slice to register on; tests inject a fake.
 * @returns the uninstaller that removes the rejection handler.
 */
 export function installFailLoud(binName: string, proc: FailLoudProcess = process): () => void {
  const handler = (err: unknown): void => {
+    if (assembledActivationRejections.has(err)) return
    proc.stderr.write(`${binName}: fatal load failure: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`)
    proc.exit(1)
  }
@@ -157,15 +361,65 @@ export function assertEntriesLoaded(ctx: Context, binName: string): void {
 }

 /**
- * Context key a bin sets through {@link boot}'s `prepare` hook to hand a resume
- * session id to the booted config: `ctx.provide(RESUME_SESSION_ID_KEY, id)`
- * makes `id` readable as the bare identifier `resumeSessionId` in a config
- * `!!js` expression. The value is the bin's already-parsed id (or `undefined`),
- * so resuming a session needs no environment variable. A bin that never
- * provides it leaves the identifier undeclared, so configs read it defensively
- * (`typeof resumeSessionId === 'string' ? resumeSessionId : undefined`).
+ * Value mirrors used because Cordis's const enum has no runtime object to import.
+ * Keep aligned with `packages/cordis/tool-cordis/src/fiber-state.ts` and
+ * `packages/client/web/src/loader-status.ts`.
 */
-export const RESUME_SESSION_ID_KEY = 'resumeSessionId'
+const FIBER_PENDING = 0 as FiberState.PENDING
+const FIBER_ACTIVE = 2 as FiberState.ACTIVE
+const FIBER_FAILED = 3 as FiberState.FAILED
+
+/** Render a thrown plugin value without discarding an Error's original stack. */
+function formatActivationError(error: unknown): string {
+  return error instanceof Error ? error.stack ?? error.message : String(error)
+}
+
+/**
+ * Reject a settled Loader tree when an enabled entry failed or remains inactive.
+ * Plugin failures include the original thrown stack; pending entries name their
+ * unresolved services because no plugin error exists for that state. Active
+ * entries require no further wait; only failed fibers are awaited to recover
+ * their private rejection reason.
+ * @param ctx - the settled context whose Loader entries to audit.
+ * @param binName - the diagnostic prefix on the thrown error.
+ * @returns nothing when every enabled entry is active.
+ * @throws after one process rejection checkpoint when an entry failed to
+ * import, rejected during activation, or did not become active.
+ */
+export async function assertEntriesActivated(ctx: Context, binName: string): Promise<void> {
+  assertEntriesLoaded(ctx, binName)
+  const failures: string[] = []
+  const rejectionReasons: unknown[] = []
+  for (const entry of ctx.loader.entries()) {
+    const fiber = entry.fiber
+    if (fiber === undefined || entry.disabled) continue
+    const state = fiber.state
+    if (state === FIBER_ACTIVE) continue
+    if (state === FIBER_FAILED) {
+      try {
+        await fiber.await()
+      } catch (error) {
+        rejectionReasons.push(error)
+        failures.push(`${entry.options.name}: ${formatActivationError(error)}`)
+      }
+      continue
+    }
+    if (state === FIBER_PENDING) {
+      const missing = Object.keys(fiber.inject).filter(service => fiber.ctx.get(service) === undefined)
+      const subject = missing.length === 1 ? 'service' : 'services'
+      failures.push(`${entry.options.name}: pending (waiting for ${subject}: ${missing.join(', ') || 'unknown'})`)
+    } else {
+      failures.push(`${entry.options.name}: fiber state ${String(state)}`)
+    }
+  }
+  if (failures.length > 0) {
+    if (rejectionReasons.length > 0) {
+      await observeLoaderRejectionCheckpoint(rejectionReasons)
+    }
+    const noun = failures.length === 1 ? 'entry' : 'entries'
+    throw new Error(`${binName}: ${String(failures.length)} ${noun} did not activate\n${failures.join('\n')}`)
+  }
+}

 /**
 * Boot the Loader against `absoluteConfigPath` and return only after the whole
@@ -175,16 +429,21 @@ export const RESUME_SESSION_ID_KEY = 'resumeSessionId'
 * bootstrap include is therefore statically imported and mounted as the
 * `cordis:include` builtin, loading through the ambient module pipeline
 * (vite/tsx/plain ESM) while the included tree's own specifiers stay
- * config-relative. A missing fiber rejects here; a later init rejection is
- * handled by {@link installFailLoud}. Built bins need the Loader's native
- * helper for bare plugin specifiers; relative specifiers do not.
+ * config-relative. The package build embeds Include while leaving Loader
+ * external, so the built include tree and host share one Loader peer. A
+ * missing fiber rejects here; a later init rejection is rethrown with its
+ * original stack by {@link assertEntriesActivated}; later unhandled
+ * rejections remain covered by {@link installFailLoud}. Built bins need the
+ * Loader's native helper for bare plugin specifiers; relative specifiers do
+ * not.
 * @param binName - the diagnostic prefix for load-failure errors.
 * @param absoluteConfigPath - the config to include; must already be absolute
 * (see {@link resolveConfigPath}).
 * @param patches - optional overlay patches applied over the included tree
 * (see {@link loadPersonalPatches}); an empty list mounts none.
- * @param prepare - optional host setup run against the root context before any Loader entry mounts.
- * @returns the root context once every entry has started.
+ * @param prepare - optional host setup run after Loader installation and before any config-tree entry mounts.
+ * @returns the root context once every entry has started, or as soon as a
+ * surface disposed the tree while startup was still in flight.
 */
 export async function boot(
  binName: string,
@@ -193,10 +452,11 @@ export async function boot(
  prepare?: (ctx: Context) => Promise<void> | void,
 ): Promise<Context> {
  const ctx = new Context()
-  await prepare?.(ctx)
  ctx.baseUrl = pathToFileURL(dirname(absoluteConfigPath)).href + '/'
+  ctx.provide('dshHomePath', dshHomePath)
  await ctx.plugin(Loader)
  ctx.loader.builtins.include = Include
+  await prepare?.(ctx)
  await ctx.loader.create({
    name: 'cordis:include',
    config: {
@@ -205,7 +465,14 @@ export async function boot(
    },
  })
  await ctx.loader.await()
-  assertEntriesLoaded(ctx, binName)
+  // A surface can finish and dispose the whole tree while that await is still
+  // pending: the TUI renders as soon as its own fiber starts, so an `/exit`
+  // typed before the last entry settles tears the context down under us. The
+  // Loader service goes with it, and the activation audit describes a live
+  // tree — reading `ctx.loader` here would throw a TypeError over an app that
+  // exited exactly as asked.
+  if (ctx.get('loader') === undefined) return ctx
+  await assertEntriesActivated(ctx, binName)
  return ctx
 }