@knyazevai/dsh 0.1.4 → 0.2.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Knyazev AI
+Copyright (c) 2026 DeepSeek
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.i18n.yaml

@@ -0,0 +1,22 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write apps/cli/README.md
+/knyazevai-dsh:
+  en: 7f209ab22bae6892
+  zh: 0beec262978f532c
+/knyazevai-dsh/entry-modes:
+  en: a1e035a813554366
+  zh: b87053214afe71b6
+/knyazevai-dsh/app-arguments:
+  en: cc03e6b75206661b
+  zh: 99e41f4143198352
+/knyazevai-dsh/profiles:
+  en: fbbccefed0aa4bf7
+  zh: 74876aced6ad2f0a
+/knyazevai-dsh/optional-overlays:
+  en: 3a40ddc44e55f79c
+  zh: 8d3949132e1ef93c
+/knyazevai-dsh/development:
+  en: 87b16c6ce185903d
+  zh: b83991dd89607c22

package/README.md

@@ -1,113 +1,64 @@
-# @knyazevai/dsh
+# `@knyazevai/dsh`
 
-Плагин [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): провайдер **Knyazev AI**, модели Flash / Kimi / MiniMax, thinking и effort `off / high / max`. После установки выбран **Flash max** — в Models остаётся только ключ.
+English | [中文](README.zh.md)
 
-## Установка
+The `dsh` command is the sole supported Node application launcher: profiles are ordered stacks of plugin-bundle patch layers under the user's own overrides. SDK and ACP are profiles, not separate public bins. The Python runtime wheel packages this same command; the SDK defaults to `sdk`, and the minimal example selects `sdk-minimal`. [`src/args.ts`](src/args.ts) owns the command grammar, and [`src/bin.ts`](src/bin.ts) loads only the selected runner. Invalid commands, options from another mode, and fatal configuration or boot failures exit nonzero.
 
-Нужны [Node.js](https://nodejs.org/) и [pnpm](https://pnpm.io/).
+## Entry modes
 
-Профили DSH — pnpm workspace, поэтому нужен `-w`.
-
-```sh
-npx @deepseek-ai/dsh plugin --profile web add -w @knyazevai/dsh
-npx @deepseek-ai/dsh web
-```
+| Command | Purpose |
+|---|---|
+| `dsh <name>` / `dsh --profile <name>` | Boot the named profile under `$DSH_HOME/profiles/<name>`. |
+| `dsh --profile <name> --from-default-profile <template>` | Replace a custom profile with a fresh copy of a shipped template, then boot it. |
+| `dsh --profile acp` | Serve automation clients over ACP stdio until disconnect. |
+| `dsh --profile headless "job"` | Run one fresh persisted session, print the final answer, and exit. |
+| `dsh --profile sdk` | Serve SDK clients over JSON-RPC stdio until shutdown or disconnect. |
+| `dsh --profile sdk-minimal` | Serve SDK clients with the standalone minimal agent tree. |
+| `dsh web` | Boot the Web profile. |
+| `dsh plugin --profile <name> <pnpm args>` | Manage a profile's plugins by forwarding to pnpm in the profile directory. |
 
-Пока пакет не на npm — ставь с GitHub:
+The invoking directory is the default workspace root. The `web`, `headless`, `sdk`, `sdk-minimal`, and `acp` profiles auto-initialize on first use from shipped templates. Create or reset another profile at a non-shipped name with `--from-default-profile`, or initialize a base-backed profile through `dsh plugin`. The `desktop` name is reserved for the Electron-owned profile, so the CLI rejects boot and config-dump requests for it. The npm CLI also rejects its plugin-management requests; the [Desktop-installed command](../desktop/README.md#bundled-command-runtime) can manage the initialized Desktop profile using that installation’s runtime.
 
-```sh
-npx @deepseek-ai/dsh plugin --profile web add -w git+https://github.com/knyazev741/knyazevai-dsh.git
-```
+## App arguments
 
-Локально из клона:
+The launcher parses only its own flags and hands everything after them to the booted profile, where any injected app plugin may parse the shared immutable snapshot ([`dsh-cmdline`](../../packages/boot/cmdline/README.md)). The first token the launcher does not recognize starts the app's arguments:
 
 ```sh
-npx @deepseek-ai/dsh plugin --profile web add -w .
+dsh --profile web --port 8080       # --port belongs to the web app
+dsh --profile tui --resume <id>     # example, assuming the tui profile is installed; --resume belongs to the terminal app
+dsh --profile headless "run the tests"
+dsh --profile web --help            # the web app's flags, not the launcher's
+dsh --help                          # the launcher's own help
 ```
 
-Для headless то же с `--profile headless`.
-
-## После установки
-
-Новые сессии сразу идут на **Knyazev AI / DeepSeek V4 Flash** с effort **max**. Kimi и MiniMax уже в пикере, сабагенты на том же маршруте.
+<a id="profiles"></a>
+## Profiles
 
-Ключ в пакет не входит. Если `KNYAZEV_AI_API_KEY` ещё не в окружении — открой Harness → Models → **Knyazev AI** и вставь `kn_live_…` из [кабинета](https://knyazevai.work). Модели выбирать не нужно.
+A profile directory holds a `package.json` (out-of-tree plugin dependencies plus the profile manifest `dsh.profile` with its ordered `bundles` list) and a `cordis.patch.yml` (the user's own patch layer). `dsh-hmr`, when enabled in YAML, watches the profile manifest and both profile and home patch files, then recomposes all layers through one serialized reload. Without HMR, changes apply on restart. Edits arriving during watcher registration use the same nonfatal reload reporting as later edits. [Plugin Manager](../../packages/boot/plugin-manager/README.md) shares package operations and the profile write lock with `dsh plugin`; package updates retain disabled bundle selections. CLI package commands inherit authentication variables and terminal descriptors, including interactive build approval; service calls retain their scrubbed environment and captured diagnostics.
 
-Не копируй YAML руками и не дублируй провайдер в `settings.yaml`. Пакет кладёт маршрут и дефолт в composition; ключ живёт в credentials. Сохранённый выбор в `settings.yaml` по-прежнему перекрывает composition.
+Installation and profile startup enforce the declared `engines.dsh` range, or DSH peer ranges when it is absent, against the same runtime version shown by `dsh --version`. Incompatible plugins require an explicitly acknowledged exact-version exemption. The [plugin manager's compatibility reference](../../packages/boot/plugin-manager/README.md#version-compatibility-and-exemptions) documents `version-exemptions`, `allow-version`, `revoke-version`, persistence, and risks.
 
-## Полная сборка с фиксом компактинга
+The tree composes over an empty root:
+- each bundle's patch in `dsh.profile.bundles` order
+- then the profile's `cordis.patch.yml`, then the home-level `$DSH_HOME/cordis.patch.yml`
+- then `--patch` overlays
 
-Обычная установка по имени использует официальный релиз DeepSeek Harness, в котором bounded-компактинг для огромных контекстов (400k) ещё не вышел. Если он нужен (большие сессии сжимаются по кусочкам, а не падают по `pi-ai stream idle timeout`) — запусти харнесс из форка с этим фиксом + плагин:
+Bundles named in `dsh.profile.bundles` resolve from the dsh installation first (`@knyazevai/dsh-base`, `@knyazevai/dsh-web-app`, `@knyazevai/dsh-headless`, `@knyazevai/dsh-sdk-app`, `@knyazevai/dsh-sdk-minimal`, `@knyazevai/dsh-acp-app`), then from the profile's own `node_modules`, where pnpm installs out-of-tree plugins.
 
-```sh
-git clone https://github.com/knyazev741/deepseek-harness
-cd deepseek-harness
-pnpm install
-pnpm run build
-pnpm dsh plugin --profile fork-web add -w @knyazevai/dsh@0.1.4
-pnpm dsh web
-```
-
-Фикс `maxSummarizationInputTokens` — код харнесса, он есть только в этой сборке; плагин несёт его конфиг (только для `knyazev-ai`).
-
-**Как форк держится свежим по upstream (автоматически, с AI-ревью).** В форке есть два воркфлоу:
-- `upstream-sync.yml` — раз в час тянет официальный `deepseek-ai/deepseek-harness` master в ветку-ПР `sync/upstream-master` (конфликты решаются в пользу форка);
-- `upstream-review.yml` — на каждом таком ПР гоняет sanity-гейты (typecheck + тесты) и прогоняет многоходовой headless-агент Knyazev (`knyazev-ai/deepseek-v4-flash`), который ревьюит дифф и отдаёт вердикт `{safe, summary, risks}`. Авто-мёрж ПР делается **только при вердикте safe**; risky остаётся человеку. Никогда ничего не деплоит.
+Use `--dump-default-config` and `--dump-config` to inspect the composed tree without booting it. `--dump-config-schema` imports the composed tree's declared plugin schemas and prints JSON Schema for entries and patches instead of configuration values; read the [schema-dump safety and scope](reference/README.md#config-schema-dump) before inspecting untrusted plugins.
 
-Для ревью в настройках репозитория форка нужен секрет `KNYAZEV_AI_API_KEY` (тот же ключ маршрута knyazev-ai).
+The [CLI behavior reference](reference/README.md) owns exact layer precedence, flags, shutdown behavior, deployment defaults, and source execution. The [startup and reload failure table](../../packages/boot/app-boot/README.md#startup-and-reload-failures) compares optional and required plugin failures with configuration HMR.
 
-Для человека обновление сводится к `git pull` в клоне + `pnpm install && pnpm run build` — сами изменения upstream уже засинканы и отревьюены на стороне форка.
-
-Пока этот фикс не в официальном релизе, обычная установка по имени compaction-фикса не даёт — только запуск из форка.
-
-## Что ставится
-
-| Поле | Значение |
-|---|---|
-| Provider | `knyazev-ai` |
-| Endpoint | `https://knyazevai.work/v1` |
-| Models | `deepseek-v4-flash`, `kimi-2.6`, `minimax-2.7` |
-| Thinking | qwen / `enable_thinking` |
-| Effort | `off`, `high`, `max` (Flash и Kimi) |
+## Optional overlays
 
-MiniMax без пикера effort: модель не отдаёт reasoning отдельным полем.
+`config/examples/` ships opt-in overlays for GitHub review webhooks, memory MCP servers, and runtime Cordis tools. They are never part of a default profile; the [user guides](../../docs/user/guide/index.md) and [developer practice guides](../../docs/user/develop/practice/index.md) own setup and safety instructions.
 
-Дефолт Harness после установки: `knyazev-ai` / `deepseek-v4-flash`, effort `max`. Сабагенты (`subagent`, `subagent_fork`) на том же маршруте.
+## Development
 
-## Обновление / снятие
+Production runs require built package and frontend artifacts. From the repository root, run `pnpm run build` separately, then use `pnpm dsh <args...>` to run the TypeScript entry and forward every argument; the [source-execution reference](reference/README.md#source-execution) owns the module-resolution contract.
 
-```sh
-npx @deepseek-ai/dsh plugin --profile web update
-npx @deepseek-ai/dsh plugin --profile web remove -w @knyazevai/dsh
-```
-
-## Релиз (публикация в npm)
-
-Пакет публикуется автоматически: GitHub Actions прогоняет тесты и на пуш тега `v<версия>` выкладывает `@knyazevai/dsh` в npm.
-
-Один раз настрой доступ:
-
-1. В npm (Account → Access Tokens) создай токен уровня **Automation** (без двухфакторки).
-2. На GitHub в репо → Settings → Secrets and variables → Actions добавь секрет `NPM_TOKEN` с этим токеном.
-3. `publishConfig.access: public` уже стоит в `package.json`.
-
-Дальше на каждый новый релиз:
-
-```sh
-npm version patch      # поднимает версию: patch | minor | major
-git push origin main
-git push origin v0.1.1 # пуш тега запускает тесты + публикацию
-```
-
-Тесты перед публикацией идут сами (`prepublishOnly` в `package.json`).
-
-Установка **по имени** — на любой машине:
-
-```sh
-npx @deepseek-ai/dsh plugin --profile web add -w @knyazevai/dsh
-npx @deepseek-ai/dsh web
-```
+The `@knyazevai/dsh/profile-boot` export provides the shared profile lifecycle to the Desktop host. A resolved application profile supplies its own installation anchor for runtime package resolution while retaining the Harness home patch, proxy environment, telemetry switch, patch reload, and bounded shutdown.
 
-## Docs
+Packaged installations call the same `runCli()` entry with their package-manager executable. The Desktop carrier also enables plugin operations for its initialized profile; npm launches omit these options. Installation-owned package environments apply only to plugin package operations; the invoking directory, ordinary profile selection, and agent-shell PATH retain their CLI meanings.
 
-https://knyazevai.work/docs
+The [Web failure matrix](tests/profiles/web/tests/web-failure-matrix.expected.e2e.ts) runs the built CLI through startup failures and native configuration HMR with `awaitWriteFinish` enabled in `test:expected`. It verifies authenticated HTTP responses, diagnostics, recovery, process exits, and disposal without model API calls; the [startup acceptance](tests/profiles/web/tests/web-best-effort-startup.expected.e2e.ts) also covers the shipped required Web dependencies and port conflicts.

package/README.zh.md

@@ -0,0 +1,64 @@
+# `@knyazevai/dsh`
+
+[English](README.md) | 中文
+
+`dsh` 是唯一受支持的 Node 应用启动器；profile 由多个插件组合包 patch 层按顺序叠加而成，其上再应用用户自己的覆盖配置。SDK 与 ACP（Agent Client Protocol）都是 profile，而不是独立的公开可执行命令。Python 运行时 wheel 包中也包含同一个命令；SDK 默认使用 `sdk`，极简示例选择 `sdk-minimal`。[`src/args.ts`](src/args.ts) 负责命令语法，[`src/bin.ts`](src/bin.ts) 只加载选中的运行器。无效命令、来自其他模式的选项，以及致命的配置或启动错误都会以非零状态退出。
+
+## 入口模式
+
+| 命令 | 用途 |
+|---|---|
+| `dsh <name>` / `dsh --profile <name>` | 启动位于 `$DSH_HOME/profiles/<name>` 的指定 profile。 |
+| `dsh --profile <name> --from-default-profile <template>` | 用随附模板的全新副本替换自定义 profile，然后启动它。 |
+| `dsh --profile acp` | 通过 ACP stdio 为自动化客户端提供服务，直至断开连接。 |
+| `dsh --profile headless "job"` | 运行一个全新的持久化会话，打印最终答案并退出。 |
+| `dsh --profile sdk` | 通过 JSON-RPC stdio 为 SDK 客户端提供服务，直至关闭或断开连接。 |
+| `dsh --profile sdk-minimal` | 以独立极简 agent（智能体）配置树为 SDK 客户端提供服务。 |
+| `dsh web` | 启动 Web profile。 |
+| `dsh plugin --profile <name> <pnpm args>` | 通过在 profile 目录中转发给 pnpm 来管理该 profile 的插件。 |
+
+运行命令时所在的目录将作为默认 workspace 根目录。`web`、`headless`、`sdk`、`sdk-minimal` 和 `acp` profile 在首次使用时会从随附模板自动初始化。使用 `--from-default-profile` 可以基于这些模板之一，在非内置名称处创建或重置其他 profile；通过 `dsh plugin` 则可以初始化一个以 base 为基础的 profile。`desktop` 名称保留给 Electron 持有的 profile，因此 CLI（命令行界面）会拒绝针对它的启动和配置 dump 请求。npm CLI 也会拒绝其插件管理请求；[Desktop 内置命令](../desktop/README.zh.md#bundled-command-runtime)可以使用该安装的运行时管理已初始化的 Desktop profile。
+
+## 应用参数
+
+启动器只解析自身的 flag，并将其后的所有内容交给已启动的 profile；注入该 profile 的任意应用插件都可以解析这份共享的不可变快照（[`dsh-cmdline`](../../packages/boot/cmdline/README.zh.md)）。启动器无法识别的第一个 token 标志着应用参数的开始：
+
+```sh
+dsh --profile web --port 8080       # --port belongs to the web app
+dsh --profile tui --resume <id>     # example, assuming the tui profile is installed; --resume belongs to the terminal app
+dsh --profile headless "run the tests"
+dsh --profile web --help            # the web app's flags, not the launcher's
+dsh --help                          # the launcher's own help
+```
+
+<a id="profiles"></a>
+## Profile
+
+profile 目录包含一个 `package.json`，其中记录树外插件依赖，以及 profile manifest（元数据清单）`dsh.profile`、其中按顺序排列的 `bundles` 列表；还包含一个 `cordis.patch.yml`，其中保存用户自己的 patch 层。在 YAML 中启用的 `dsh-hmr` 监视 profile manifest、profile 与 home 级 patch 文件，再通过统一串行重载重新组合所有层。未启用 HMR 时，更改在重启后生效。监听器注册期间发生的编辑与后续编辑使用相同的非致命重载错误报告。[插件管理器](../../packages/boot/plugin-manager/README.zh.md) 与 `dsh plugin` 共享包操作和 profile 写锁；更新依赖会保留已停用的组合包选择。CLI 包操作继承认证环境和终端描述符，支持交互式构建批准；service 调用保留清理后的环境并捕获诊断。
+
+安装和 profile 启动会按声明的 `engines.dsh` 范围（未声明时按 DSH peer 范围），检查与 `dsh --version` 显示值相同的运行时版本。不兼容插件需要用户明确确认精确版本豁免。[插件管理器的兼容性参考](../../packages/boot/plugin-manager/README.zh.md#version-compatibility-and-exemptions)说明 `version-exemptions`、`allow-version`、`revoke-version`、持久化规则与风险。
+
+配置树以空根为起点，依次叠加以下配置层：
+- `dsh.profile.bundles` 中各组合包的 patch
+- profile 自身的 `cordis.patch.yml`，然后是 home 级的 `$DSH_HOME/cordis.patch.yml`
+- `--patch` 指定的覆盖层
+
+`dsh.profile.bundles` 中列出的组合包先从 dsh 安装目录解析（`@knyazevai/dsh-base`、`@knyazevai/dsh-web-app`、`@knyazevai/dsh-headless`、`@knyazevai/dsh-sdk-app`、`@knyazevai/dsh-sdk-minimal`、`@knyazevai/dsh-acp-app`），再从 profile 自身的 `node_modules` 解析；pnpm 会将树外插件安装到该目录。
+
+使用 `--dump-default-config` 和 `--dump-config` 可在不启动的情况下检查组合后的配置树。`--dump-config-schema` 会导入组合树中插件声明的 schema，并打印描述 entry 与 patch 的 JSON Schema，而不是配置值；检查不受信任的插件前，请阅读 [schema dump 的安全性与范围](reference/README.zh.md#config-schema-dump)。
+
+层的确切优先级、flag、关闭行为、部署默认值和源码执行方式，以 [CLI 行为参考](reference/README.zh.md)为准。[启动与重载失败表](../../packages/boot/app-boot/README.zh.md#startup-and-reload-failures)对比 optional、required 插件启动失败与配置 HMR 的行为。
+
+## 可选覆盖层
+
+`config/examples/` 交付 GitHub 评审 webhook、记忆 MCP 服务器与运行时 Cordis 工具的可选覆盖层。它们绝不属于默认 profile；设置与安全说明由[用户指南](../../docs/user/guide/index.zh.md)和[开发实战指南](../../docs/user/develop/practice/index.zh.md)负责。
+
+## 开发
+
+生产运行需要已构建的包与前端产物。请在仓库根目录单独运行 `pnpm run build`，然后使用 `pnpm dsh <args...>` 运行 TypeScript 入口并转发所有参数；模块解析约定以[源码执行参考](reference/README.zh.md#source-execution)为准。
+
+`@knyazevai/dsh/profile-boot` 导出向 Desktop Host 提供共享 profile 生命周期。已解析的应用 profile 为运行时包解析指定自己的安装锚点，同时沿用 Harness home patch、代理环境、遥测开关、patch 热重载和有界关闭。
+
+打包安装通过同一个 `runCli()` 入口传入包管理器可执行文件。Desktop 载体还会启用其已初始化 profile 的插件操作；npm 启动不传入这些选项。安装包提供的包管理环境仅用于插件包操作；调用目录、普通 profile 选择与 agent shell 的 PATH 保留 CLI 语义。
+
+[Web 失败矩阵](tests/profiles/web/tests/web-failure-matrix.expected.e2e.ts)在 `test:expected` 中通过构建后的 CLI 验证启动失败与启用 `awaitWriteFinish` 的原生配置 HMR。它不调用模型 API，而是检查经过认证的 HTTP 响应、诊断、恢复、进程退出与 dispose；[启动验收测试](tests/profiles/web/tests/web-best-effort-startup.expected.e2e.ts)还覆盖随附 Web 的必需依赖与端口冲突。

package/bin.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+// A workspace install must run the checkout's source launcher; an npm install
+// outside the repository must run the packaged build.
+
+import { existsSync, realpathSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+
+const packageRoot = dirname(realpathSync(fileURLToPath(import.meta.url)))
+const repositoryRoot = resolve(packageRoot, '../..')
+const repositoryEntry = join(repositoryRoot, 'scripts/repo-dsh.ts')
+const inRepository = existsSync(repositoryEntry) && existsSync(join(repositoryRoot, 'pnpm-workspace.yaml'))
+const args = inRepository
+  ? ['--import', 'tsx/esm', repositoryEntry, ...process.argv.slice(2)]
+  : [join(packageRoot, 'lib/bin.js'), ...process.argv.slice(2)]
+const result = spawnSync(process.execPath, args, { env: process.env, stdio: 'inherit' })
+
+if (result.error !== undefined) {
+  process.stderr.write(`dsh: could not start Node: ${result.error.message}\n`)
+  process.exit(1)
+}
+
+process.exit(result.status ?? 1)

package/lib/bin.js

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+import { StartupError, getDshRuntimeVersion, loadLayeredEnv } from "@knyazevai/dsh-app-boot";
+import { resolveDshHome } from "@knyazevai/dsh-home-paths";
+import { Command, CommanderError, InvalidArgumentError } from "commander";
+import { randomUUID } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { inspect } from "node:util";
+//#region lib/types/args.js
+/**
+* Commander adapter for the `dsh` command line.
+*
+* The launcher parses only what it owns — which profile to boot, which extra
+* patch overlays to apply, and the config dumps — and hands **everything after
+* its own flags** to the booted tree verbatim, where injected app plugins parse
+* their own flag families and print their own `--help` (see
+* `@knyazevai/dsh-cmdline`). Launcher flags therefore come first: the first
+* token this parser does not recognize starts the inner arguments, so
+* `dsh --profile tui --resume abc` boots the tui profile with `--resume abc`,
+* and `dsh --profile web -h` prints the web app's help, not this one's.
+*
+* `dsh <name>` abbreviates `dsh --profile <name>`; `plugin` manages a profile's
+* plugin dependencies by forwarding to pnpm.
+* @module @knyazevai/dsh/args
+*/
+/**
+* Repeatable single-value collector: `--patch a.yml --patch b.yml`. Never
+* variadic — a variadic `--patch` would swallow the inner arguments.
+*/
+const collect = (value, previous = []) => [...previous, value];
+function selectProfile(value, previous) {
+	if (previous !== void 0) throw new InvalidArgumentError("select a profile only once");
+	return value;
+}
+function rejectElectronProfile(program, profile) {
+	if (profile.toLowerCase() === "desktop") program.error("error: profile \"desktop\" is managed exclusively by the Electron application");
+}
+/** The launcher's own help text; each app prints its own. */
+const HELP_EXAMPLES = `
+Examples:
+  dsh web                                   boot the web profile (same as: dsh --profile web)
+  dsh rescue --from-default-profile web
+                                            recreate rescue from the shipped web template, then boot it
+  dsh headless "run the tests"              answer one task, print the result, and exit
+  dsh tui --patch ./extra.yml               boot a custom profile with one extra overlay
+  dsh tui --resume <session>                arguments after the launcher flags reach the app
+  dsh web --help                            the web app's own flags and help
+  dsh plugin --profile tui add <package>    install a plugin into the tui profile
+`;
+/**
+* Resolve a boot or dump invocation from the launcher flags and the leftover
+* inner arguments.
+* @param program - the command whose options were parsed.
+* @param profile - the profile these flags boot.
+* @param options - the launcher flags commander collected.
+* @param args - the leftover arguments, in argv order.
+* @returns the resolved invocation.
+*/
+function resolveBoot(program, profile, options, args) {
+	const patches = options.patch ?? [];
+	if (patches.includes("")) program.error("error: --patch needs a path");
+	if (options.fromDefaultProfile === "") program.error("error: --from-default-profile needs a name");
+	const dumps = [
+		options.dumpConfig,
+		options.dumpDefaultConfig,
+		options.dumpConfigSchema
+	].filter(Boolean);
+	if (dumps.length === 0) return {
+		mode: "profile",
+		profile,
+		fromDefaultProfile: options.fromDefaultProfile,
+		patches,
+		args
+	};
+	if (dumps.length > 1) program.error("error: --dump-config, --dump-default-config, and --dump-config-schema are mutually exclusive");
+	if (args.length > 0) program.error(`error: config dumps take no app arguments, got ${args.map((argument) => JSON.stringify(argument)).join(" ")}`);
+	if (options.dumpConfigSchema === true) return {
+		mode: "dump-config-schema",
+		profile,
+		fromDefaultProfile: options.fromDefaultProfile,
+		patches
+	};
+	const defaultOnly = options.dumpDefaultConfig === true;
+	if (defaultOnly && patches.length > 0) program.error("error: --dump-default-config prints the bundle layers and takes no --patch");
+	return {
+		mode: "dump-config",
+		profile,
+		fromDefaultProfile: options.fromDefaultProfile,
+		defaultOnly,
+		patches
+	};
+}
+/**
+* Resolve argv into one invocation, or print and exit for help, version, or an
+* error.
+* @param argv - arguments after the Node binary and script.
+* @param version - version string printed by `--version`.
+* @param manageDesktopProfile - permit Desktop's installed carrier to manage its reserved profile's plugins.
+* @returns the resolved invocation.
+*/
+function parseDshArgs(argv, version, manageDesktopProfile = false) {
+	const first = argv[0];
+	const webProfile = process.env.DSH_REPOSITORY_WEB_PROFILE ?? "fork-web";
+	if (webProfile === "") throw new Error("DSH_REPOSITORY_WEB_PROFILE needs a profile name");
+	let resolved;
+	const program = new Command();
+	program.name("dsh").version(version, "-V, --version", "output the version number").usage("[--profile] <name> [options] [app-args...]\n       dsh plugin --profile <name> <pnpm-args...>").description("dsh: boot a DeepSeek Harness profile — an ordered stack of plugin-bundle patch layers under your own overrides.").addHelpText("after", HELP_EXAMPLES).exitOverride().helpOption(false).helpCommand(false).allowUnknownOption().passThroughOptions().enablePositionalOptions().argument("[args...]", "arguments for the booted profile's app (see: dsh --profile <name> --help)").option("--profile <name>", "the profile under $DSH_HOME/profiles to boot", selectProfile).option("--from-default-profile <name>", "replace a custom profile with a fresh copy of a shipped profile template").option("--patch <path>", "extra patch-list overlay applied after the profile layer (repeatable)", collect).option("--dump-config", "print the composed profile tree and exit").option("--dump-config-schema", "print JSON Schema for profile entries and patches without mounting").option("--dump-default-config", "print the profile tree without its user layer or --patch overlays and exit").action((args, options) => {
+		if (options.profile === void 0) {
+			if (args.some((argument) => argument === "-h" || argument === "--help")) program.help();
+			program.error("error: --profile <name> is required");
+		}
+		const profile = options.profile;
+		if (profile === "") program.error("error: --profile needs a name");
+		rejectElectronProfile(program, profile);
+		resolved = resolveBoot(program, profile, options, args);
+	});
+	if (first === "plugin") {
+		const plugin = program.command("plugin").description("manage a profile's plugins by forwarding the remaining arguments to pnpm in the profile directory");
+		plugin.helpOption("-h, --help", "show this help").passThroughOptions().requiredOption("--profile <name>", "the profile whose plugins to manage (initialized on first use)", selectProfile).allowUnknownOption().argument("[args...]", "pnpm arguments, forwarded verbatim (add <pkg>, remove <pkg>, why <pkg>, ...)").action((args, options) => {
+			if (options.profile === "") program.error("error: --profile needs a name");
+			if (!manageDesktopProfile) rejectElectronProfile(plugin, options.profile);
+			if (args.length === 0) program.error("error: plugin needs pnpm arguments to forward (e.g. add <package>)");
+			resolved = {
+				mode: "plugin",
+				profile: options.profile.toLowerCase() === "desktop" ? "desktop" : options.profile,
+				args
+			};
+		});
+	}
+	try {
+		const expanded = first !== void 0 && !first.startsWith("-") && first !== "plugin" ? [
+			"--profile",
+			first === "web" ? webProfile : first,
+			...argv.slice(1)
+		] : argv;
+		program.parse(expanded, { from: "user" });
+	} catch (error) {
+		return process.exit(error instanceof CommanderError ? error.exitCode : 1);
+	}
+	/* v8 ignore next -- an action resolves or Commander throws */
+	if (resolved === void 0) throw new Error("dsh: no invocation resolved");
+	return resolved;
+}
+//#endregion
+//#region lib/types/startup-diagnostics.js
+/** Save original startup diagnostics while keeping the terminal report concise. */
+/** Wait for stderr to finish the write before the failed process exits. */
+function writeStderr(text) {
+	return new Promise((resolve, reject) => {
+		process.stderr.write(text, (error) => {
+			if (error) reject(error);
+			else resolve();
+		});
+	});
+}
+/**
+* Print the startup summary and save a private, uniquely named report under DSH_HOME/logs.
+* Failed writes print the complete report to stderr instead of claiming a saved path.
+* @param error - startup audit failure retaining plugin metadata and original errors.
+* @param context - resolved Harness home, application version, and selected profile.
+* @param write - terminal output sink; awaited before returning, defaults to stderr.
+* @returns after saving or printing the report and completing terminal writes.
+*/
+async function reportStartupFailure(error, context, write = writeStderr) {
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const report = "WARNING: Raw diagnostics may contain configuration or credential values from plugin errors. Review before sharing.\n\n" + inspect({
+		timestamp: now,
+		dshVersion: context.version,
+		nodeVersion: process.version,
+		platform: process.platform,
+		arch: process.arch,
+		profile: context.profile,
+		error
+	}, {
+		depth: null,
+		maxArrayLength: null,
+		maxStringLength: null,
+		showHidden: true,
+		customInspect: false,
+		getters: false,
+		colors: false
+	}) + "\n";
+	await write(`${error.message}\n`);
+	const logDir = join(context.home, "logs");
+	const logPath = join(logDir, `startup-${now.replaceAll(":", "-")}-${randomUUID()}.log`);
+	try {
+		await mkdir(logDir, {
+			recursive: true,
+			mode: 448
+		});
+		await writeFile(logPath, report, {
+			flag: "wx",
+			mode: 384
+		});
+	} catch (writeError) {
+		await write(`\ndsh: warning: could not write startup diagnostics: ${String(writeError)}\nFull diagnostics:\n${report}`);
+		return;
+	}
+	await write(`\nFull diagnostics: ${logPath}\n`);
+}
+//#endregion
+//#region lib/types/bin.js
+/**
+* Command-line entry for dsh.
+* @module @knyazevai/dsh/bin
+*/
+/* v8 ignore file -- built-bin acceptance exercises this self-executing dispatch. */
+/**
+* Run the public dsh command-line interface.
+* @param options - Package runtime and Desktop profile access supplied by the installation.
+* @returns a promise that settles when the selected command mode finishes.
+*/
+async function runCli(options = {}) {
+	const version = getDshRuntimeVersion();
+	const { manageDesktopProfile, ...profileOptions } = options;
+	const invocation = parseDshArgs(process.argv.slice(2), version, manageDesktopProfile);
+	switch (invocation.mode) {
+		case "profile": {
+			const { runProfile } = await import("./profile-boot.js");
+			try {
+				await runProfile({
+					environment: loadLayeredEnv("dsh"),
+					profile: invocation.profile,
+					fromDefaultProfile: invocation.fromDefaultProfile,
+					patchFiles: invocation.patches,
+					args: invocation.args,
+					...profileOptions
+				});
+			} catch (error) {
+				if (!(error instanceof StartupError)) throw error;
+				await reportStartupFailure(error, {
+					home: resolveDshHome(),
+					version,
+					profile: invocation.profile
+				});
+				process.exit(1);
+			}
+			break;
+		}
+		case "plugin": {
+			const { runPlugin } = await import("./plugin-CjFov5EZ.js");
+			process.exit(await runPlugin(invocation.profile, invocation.args, options.packageManager));
+			break;
+		}
+		case "dump-config": {
+			const { runDumpConfig } = await import("./dump-config-Cxlnwi7L.js");
+			runDumpConfig(invocation.profile, invocation.defaultOnly, invocation.patches, invocation.fromDefaultProfile);
+			break;
+		}
+		case "dump-config-schema": {
+			const { runDumpConfigSchema } = await import("./dump-config-schema-CzGcS3DG.js");
+			await runDumpConfigSchema(invocation.profile, invocation.patches, invocation.fromDefaultProfile);
+			break;
+		}
+		default: throw new Error(`dsh: unhandled invocation mode ${JSON.stringify(invocation)}`);
+	}
+}
+if (import.meta.main) await runCli();
+//#endregion
+export { runCli };

package/lib/dump-config-Cxlnwi7L.js

@@ -0,0 +1,2 @@
+import { n as runDumpConfig } from "./dump-config-DC1v_CSl.js";
+export { runDumpConfig };

package/lib/dump-config-DC1v_CSl.js

@@ -0,0 +1,64 @@
+import { a as prepareProfile, n as PROFILE_ROOT_FILENAME, r as homePatchPath } from "./profile-boot-B44a52oE.js";
+import { loadOptionalPatches, loadOverlayPatches, renderConfigDump } from "@knyazevai/dsh-app-boot";
+import { join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+//#region lib/types/dump-config.js
+/**
+* Config-dump entry for `dsh --profile <name> --dump-config`: compose the
+* profile's patch layers through the include plugin's patch algorithm without
+* booting or evaluating `!!js`, with one source layer per bundle, the
+* profile's own patch file, and each `--patch` overlay.
+* @module @knyazevai/dsh/dump-config
+*/
+const NAME = "dsh";
+/* v8 ignore start -- built-bin acceptance drives this boot-free dispatch */
+/**
+* Print a profile composition with comments naming each source file and patch layer.
+* @param profile - the profile name.
+* @param defaultOnly - omit the profile's user layer and `--patch` overlays
+* (the recovery diagnostic for a broken `cordis.patch.yml`, which is then
+* never parsed).
+* @param patches - `--patch` overlay paths, in argv order.
+* @param fromDefaultProfile - shipped template that replaces the profile before loading it.
+*/
+function runDumpConfig(profile, defaultOnly, patches, fromDefaultProfile) {
+	const loaded = prepareProfile(profile, !defaultOnly, fromDefaultProfile);
+	const layers = collectConfigDumpLayers(loaded, defaultOnly, patches);
+	process.stdout.write(renderConfigDump(NAME, join(loaded.dir, PROFILE_ROOT_FILENAME), layers));
+}
+/**
+* Read dump layers in bundle, profile, home, then argv order without composing them.
+* @param loaded - prepared profile and parsed bundle and profile patches.
+* @param defaultOnly - omit profile, home, and argv layers without reading their files.
+* @param patches - overlay paths relative to the invoking directory, in argv order.
+* @returns the labeled layers shared by YAML and schema dumps.
+*/
+function collectConfigDumpLayers(loaded, defaultOnly, patches) {
+	const layers = loaded.layers.map((layer) => ({
+		label: layer.packageName,
+		patches: layer.patches
+	}));
+	if (!defaultOnly) {
+		if (existsSync(loaded.patchPath)) layers.push({
+			label: loaded.patchPath,
+			patches: loaded.patches
+		});
+		const homePatchFile = homePatchPath();
+		const homePatches = loadOptionalPatches(NAME, homePatchFile);
+		if (homePatches !== void 0) layers.push({
+			label: homePatchFile,
+			patches: homePatches
+		});
+		for (const file of patches) {
+			const absolute = resolve(file);
+			layers.push({
+				label: absolute,
+				patches: loadOverlayPatches(NAME, absolute)
+			});
+		}
+	}
+	return layers;
+}
+/* v8 ignore stop */
+//#endregion
+export { runDumpConfig as n, collectConfigDumpLayers as t };