@deepseek-ai/dsh 0.0.1-rc.1

package/config/agent-presets/cordis/skills/editing-cordis-compositions/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: editing-cordis-compositions
+description: Use when creating or changing a Cordis composition for this harness — writing or editing an agent preset, adding or removing a plugin row, deciding whether something belongs to the host composition or to one session, or diagnosing a row that mounted but contributed nothing.
+---
+
+# Editing Cordis compositions
+
+Every capability in this harness is a plugin row in a `cordis.yml`. There is no separate configuration language: changing what an agent can do means changing which rows are composed for it.
+
+## Decide the plane first
+
+Two planes, and the choice is not about how "agent-related" something feels — it is about whether the thing must be shared.
+
+**Host composition.** The registries themselves (`tools`, `systemPrompt`, `agents`, `agent-loop`, `sessions`), anything crossing sessions (persistence, session query, storage, settings, credentials, telemetry), the sandbox and approval stack, the model route, and the subagent registry with its spawn/fork backends. One instance for the process.
+
+**Agent preset.** What one session contributes to those registries: its tool plugins, its persona and prompt sections, its compaction policy. One instance per session, mounted under that session's scope and unwound with it.
+
+**A service with a consumer outside the agent plane cannot move into a preset.** `subagents` is the worked example: the registry answers cross-session queries for the host api-proxy, so a per-session copy both starves that host row — it waits forever for a service nothing provides — and collides on the second session, since a provider name registers once. The preset contributes the delegation *tools*; the registry and its backends stay host-side.
+
+A preset is a directory holding one `agent.cordis.yml`, optionally beside a `preset.yml` carrying display metadata — `name` and `description` (and, for shipped presets, a roster `order`). Write the metadata too: a preset without it shows up in every picker as its bare directory name. The shipped presets live beside the deployment's composition; locally authored ones live under `${DSH_HOME:-$HOME/.dsh}/.agent-presets/<name>/`.
+
+## Authoring a preset
+
+1. **Start from a copy.** Read a shipped composition close to what you want (the `standard` preset is the full coding agent) and copy its whole directory into `${DSH_HOME:-$HOME/.dsh}/.agent-presets/<id>/` — the id must be lowercase letters, digits, and hyphens, because it becomes the directory name. A composition written from scratch usually forgets a group realm or a consumer row; a copy starts loadable.
+2. **Expect the file sandbox.** The preset root lies outside the session workspace, so under the default `workspace-write` policy the first write is denied. Retry that exact command once with `sandbox_permissions` escalation and a short justification — the user sees and approves it. Batch your writes (one heredoc per file) rather than escalating many small commands.
+3. **Rewrite `preset.yml`**: give the copy its own `name` and `description`, and drop any `order` the source declared — that field sorts the shipped roster.
+4. **Edit `agent.cordis.yml`** row by row, keeping the plane rule and realm rule above.
+
+### Native product subagents
+
+Codex and Claude Code providers already live in the host composition. A preset chooses either product by contributing the same ordinary delegation-tool row used for spawn and fork; never move a product provider into the preset and never add a product-specific settings field.
+
+Copy these disabled templates from a shipped full preset and remove `disabled` only for the products the user requested:
+
+```yaml
+- id: tool-subagent-codex
+  name: '@deepseek-ai/dsh-tool-subagent'
+  disabled: true
+  config:
+    provider: codex
+    toolName: subagent_codex
+    enableRunInBackground: false
+    maxDepth: provider-managed
+
+- id: tool-subagent-claude-code
+  name: '@deepseek-ai/dsh-tool-subagent'
+  disabled: true
+  config:
+    provider: claude-code
+    toolName: subagent_claude_code
+    enableRunInBackground: false
+    maxDepth: provider-managed
+```
+
+The two rows are independent. Leaving both disabled preserves the copied preset, enabling one exposes only that product tool, and enabling both exposes both. The host must provide `codex` or `claude` on `PATH`; the preset does not install, authenticate, select a model for, or probe either product.
+
+The shipped preset directories are off-limits: never edit or delete them, and never escalate the sandbox to reach them, even when a change there looks quicker — an upgrade overwrites the install, and corrupting the `cordis` preset disables preset authoring itself. Locally authored presets under the user root are yours to create, edit, and delete.
+
+## The rule that catches people
+
+**A row that publishes a service may not sit loose in a preset.** Registering a service without an isolate realm puts it in the process-global realm, so the second session mounting that preset collides with the first. The mount rejects it rather than letting the collision surface later.
+
+Whether a row publishes a service is not visible from its name. `tool-bash` reads like a tool but provides `bashEnv`. Check the package's README, or mount the preset and read the rejection — it names the offending service.
+
+When a preset genuinely owns a service, wrap the provider **and every consumer that reaches it** in one group carrying an `isolate` realm:
+
+```yaml
+- id: tasks
+  name: cordis:group
+  group: true
+  isolate:
+    tasks: true
+  config:
+    - id: tasks-local
+      name: '@deepseek-ai/dsh-tasks-local'
+    - id: tool-tasks
+      name: '@deepseek-ai/dsh-tool-tasks'
+```
+
+`true` means a realm private to each mounting session. A string label instead pools one instance across every subtree naming that label — use it only for something genuinely expensive to duplicate.
+
+A consumer left outside the group resolves the host's registry, which the preset did not populate, and then contributes nothing. That is the quietest failure here: the mount succeeds and a tool is simply missing.
+
+Host capabilities exposed through registries need no realm: the host `tools` and `skills` registries are layered per scope, so rows like `skill-local` and `tool-skill` sit loose in the preset and their registrations file into this preset's layer automatically — the agent's catalog merges them with whatever the deployment registered globally.
+
+## Verifying a change
+
+Read the live runtime with `cordis_inspect` — it reports the services, the plugin fibers, and the registered tools as they actually are, which is the only reliable check that a row did what its name suggests. Note it shows THIS session's composition: a preset you just wrote is not mounted anywhere until a session starts on it.
+
+To check a preset you authored, re-read the files and validate these fields: the top level is a YAML list, every row is a map with a `name`, every group carries its own list, and service-publishing rows sit behind an `isolate` realm. The settings page's preset roster validates the same fields and marks an unloadable preset broken in red — point the user there, and ask them to start a session on the new preset to confirm the tool list; you cannot start one yourself.
+
+`cordis_mount` evaluates JavaScript against the live runtime and disappears on restart. It is for probing, not for shipping a capability: a capability belongs in a composition file.
+
+## What not to move into a preset
+
+`agent-loop` registers the one agent factory and throws on a second. The registries own the per-session layering and cannot themselves be per-session. Session persistence must stay host-side or the session list fragments. The sandbox, approval, and permission rows are a deliberate boundary: a preset is exactly as privileged as the plugins it names, so letting one relax its own confinement would defeat the confinement.

package/config/agent-presets/minimal/agent.cordis.yml

@@ -0,0 +1,70 @@
+# The `minimal` agent preset: a fixed-prompt, two-tool coding surface.
+#
+# The persona is the complete system prompt, so global identity, Web surface,
+# tool guidance, and later assembly listeners cannot add prompt text. The model
+# composes only the persistent `bash` and `str_replace_editor` tools.
+
+- id: persona
+  name: '@deepseek-ai/dsh-persona'
+  config:
+    text: You are a helpful software engineer assistant.
+    complete: true
+
+# The PTY registry is an agent-owned service, so it lives in an entry-local
+# realm. The backend still consumes the host sandbox policy and subprocess
+# implementation, while the tool registers into this agent's scoped catalog.
+- id: persistent-shell
+  name: cordis:group
+  group: true
+  isolate:
+    pty: true
+  config:
+    - id: pty
+      name: '@deepseek-ai/dsh-pty'
+
+    - id: pty-local
+      name: '@deepseek-ai/dsh-pty-local'
+      config:
+        timeoutMs: 300000
+
+    - id: persistent-bash
+      name: '@deepseek-ai/dsh-tool-bash-persistent'
+      config:
+        timeoutMs: 300000
+        description: |-
+          Run commands in a bash shell
+          * When invoking this tool, the contents of the "command" parameter does NOT need to be XML-escaped.
+          * You don't have access to the internet via this tool.
+          * You do have access to a mirror of common linux and python packages via apt and pip.
+          * State is persistent across command calls and discussions with the user.
+          * To inspect a particular line range of a file, e.g. lines 10-25, try 'sed -n 10,25p /path/to/the/file'.
+          * Please avoid commands that may produce a very large amount of output.
+          * Please run long lived commands in the background, e.g. 'sleep 10 &' or start a server in the background.
+
+# The editor requires absolute paths unconditionally.
+- id: str-replace-editor
+  name: '@deepseek-ai/dsh-tool-str-replace-editor'
+  config:
+    maxOutputChars: 16000
+
+# Model capacity comes from routed model metadata; this block states the
+# compaction policy explicitly.
+- id: compaction
+  name: cordis:group
+  group: true
+  isolate:
+    tokenMeter: true
+    compact: true
+  config:
+    - id: token-meter
+      name: '@deepseek-ai/dsh-token-meter'
+
+    - id: compact-basic
+      name: '@deepseek-ai/dsh-compact-basic'
+      config:
+        thresholdRatio: 0.8
+        retainTokens: 20480
+        summarizationProvider: ''
+        summarizationModel: ''
+        maxTokens: 8192
+        compactionRetries: 1

package/config/agent-presets/minimal/preset.yml

@@ -0,0 +1,3 @@
+name: 极简模式
+description: 仅提供持久 bash 与 str_replace_editor 的双工具编码 Agent。
+order: 3

package/config/agent-presets/standard/agent.cordis.yml

@@ -0,0 +1,243 @@
+# The `standard` agent preset: the full coding agent, mounted once per process.
+#
+# This file is an AGENT-PLANE composition. The roster mounts it ONCE under a
+# standing scope; every session naming it joins by scope parentage, so the
+# tools and prompt sections registered here cover each joined agent while a
+# session's own state stays keyed per Session/Agent inside the plugins. The
+# host composition (`base.cordis.yml` + `web.cordis.yml`) keeps everything a
+# preset must not own: the registries themselves, the sandbox and approval
+# stack, persistence, and the model route.
+#
+# A service row here MUST sit inside a group carrying an `isolate` realm.
+# Without one it publishes into the root realm, where it is process-global —
+# another preset publishing the same name collides, and a host reader would
+# resolve one preset's instance for every session; `dsh-agent-presets` rejects
+# that at mount. `true` means an entry-local realm: this standing mount's own
+# private instance, apart from every other preset's. (A shared label does NOT
+# pool instances — `provide()` throws on the second registration under the
+# same realm symbol; labels join REALMS, and are not what this file needs.)
+
+# ── identity ────────────────────────────────────────────────────────────────
+
+# The preset's own persona, shadowing the deployment default for this agent.
+# `{{model}}` and `{{cwd}}` resolve from the agent's own route and workspace.
+- id: persona
+  name: '@deepseek-ai/dsh-persona'
+  config:
+    text: >-
+      You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.
+
+- id: workspace-context
+  name: '@deepseek-ai/dsh-workspace-context'
+  config:
+    maxBytes: 65536
+
+# ── shell ───────────────────────────────────────────────────────────────────
+
+# `bash-env` stays in the HOST composition: `apps/cli/src/web.ts` injects it to
+# publish `DSH_WEB_URL`/`DSH_WEB_MODE`, and a host row that injects a service is
+# the criterion for host-plane ownership — injection resolves before any session
+# exists, so there is no agent to key by. Behind a preset realm those variables
+# never reached the model's shell at all. `tool-bash` consumes the host registry
+# from here; the executor behind it (`bash-sandbox`) is host-plane too, where the
+# sandbox policy owns it.
+- id: tool-bash
+  name: '@deepseek-ai/dsh-tool-bash'
+
+# ── filesystem ──────────────────────────────────────────────────────────────
+
+# Both register into the host `tools` registry and provide nothing, so
+# they need no realm. The `fs` service and its policy stay in the host.
+- id: tool-fs
+  name: '@deepseek-ai/dsh-tool-fs'
+
+- id: tool-fs-search
+  name: '@deepseek-ai/dsh-tool-fs-search'
+  config:
+    sampleOverCapGlobResults: false
+
+# ── background tasks ────────────────────────────────────────────────────────
+
+# Only the model-facing controls. The task REGISTRY stays on the host plane:
+# its producers sit outside any realm this file could put it in — `tool-bash`
+# above resolves it with `ctx.get`, and an entry-local realm here is invisible
+# to every sibling row, so `run_in_background` would answer "background tasks
+# unavailable" while these controls sat in the catalog. The registry is keyed by
+# owning agent anyway, so one host instance serves every session. What a preset
+# chooses is whether its agent can collect and stop background work at all.
+- id: tool-tasks
+  name: '@deepseek-ai/dsh-tool-tasks'
+
+# ── skills ──────────────────────────────────────────────────────────────────
+
+# The skill REGISTRY lives in the host composition and is layered per scope:
+# these rows register into THIS preset's layer of it, so they need no realm.
+# `skill-local` contributes local-root discovery for agents on this preset, and
+# `tool-skill` gives them the catalog and loader; the merged catalog also
+# carries whatever the deployment registered globally (repository plugins).
+- id: skill-local
+  name: '@deepseek-ai/dsh-skill-local'
+
+- id: tool-skill
+  name: '@deepseek-ai/dsh-tool-skill'
+
+# ── goals ───────────────────────────────────────────────────────────────────
+
+# Only the model-facing tool. The goal SERVICE, its session driver, and the
+# `/goal` command stay on the host plane: the Gateway serves the goal domain as
+# Remote endpoints whose receiver comes from a generated descriptor, so it
+# resolves `goals` on the host and an entry-local realm here would hide it. The
+# registry is keyed by session anyway, so one host instance serves every
+# session. What a preset chooses is whether its agent can call the goal tool.
+- id: tool-goal
+  name: '@deepseek-ai/dsh-tool-goal'
+
+# ── plan mode ───────────────────────────────────────────────────────────────
+
+# Plan state is per-agent by nature, so an entry-local realm is not a
+# workaround here — it is the correct lifetime.
+- id: planning
+  name: cordis:group
+  group: true
+  isolate:
+    planMode: true
+  config:
+    - id: plan-mode
+      name: '@deepseek-ai/dsh-plan-mode'
+      config:
+        section: |
+              You are in plan mode. Stay in plan mode until exit_plan_mode succeeds or the user switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
+
+              Explore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.
+
+              The tool catalog stays the same across modes for request-cache stability. These plan-mode rules override any later tool description or guidance that suggests using mutation tools; those tools remain listed to keep the tool catalog unchanged. Do not use todo_write to track this planning phase: it tracks implementation after an approved plan, while the plan itself belongs in exit_plan_mode.
+
+              Resolve discoverable facts by inspection. Use ask_user_question only for user-owned choices or material ambiguity that inspection cannot answer. Do not ask the user where code lives or how current behavior works when you can find out.
+
+              Make the plan decision-complete: state the goal and success criteria; group implementation changes by subsystem; identify public API, schema, and data-flow changes; cover edge cases, failure modes, tests, acceptance criteria, and explicit assumptions. Keep it concise enough to review but detailed enough that another engineer can implement it without making design decisions.
+
+              When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
+
+# ── compaction ──────────────────────────────────────────────────────────────
+
+# `compact-basic` reads `toolResultPrune` through `ctx.get`, so the pruner must
+# share this realm rather than sit outside it.
+- id: compaction
+  name: cordis:group
+  group: true
+  isolate:
+    tokenMeter: true
+    compact: true
+    toolResultPrune: true
+  config:
+    - id: token-meter
+      name: '@deepseek-ai/dsh-token-meter'
+
+    - id: compact-basic
+      name: '@deepseek-ai/dsh-compact-basic'
+
+    - id: command-compact
+      name: '@deepseek-ai/dsh-command-compact'
+
+    - id: tool-result-prune
+      name: '@deepseek-ai/dsh-compact-tool-result-prune'
+      config:
+        thresholdChars: 8192
+        headChars: 4096
+        tailChars: 1024
+
+# ── delegation and workflows ────────────────────────────────────────────────
+
+# The `subagents` registry and its spawn/fork backends live in the HOST
+# composition: the registry is a process singleton whose cross-session queries
+# the api-proxy serves to the browser, and a provider name may only be
+# registered once. This preset contributes the delegation TOOLS, which resolve
+# that host registry.
+#
+# `workflows` is different — nothing outside an agent reads it — so every row
+# that reaches it shares one entry-local realm here, and a consumer left
+# outside would resolve a host registry this preset does not populate.
+#
+# `tool-subagent-report` is host-plane for the same reason as the registry,
+# not because a preset may not want it: it registers a CONTINUABLE SETUP on
+# that singleton rather than a tool this agent calls, and the setup list is
+# not scope-aware — one copy per mounted preset means every child gets
+# `report` registered once per live session, which throws on the second.
+- id: delegation
+  name: cordis:group
+  group: true
+  isolate:
+    workflows: true
+  config:
+    - id: tool-subagent-control
+      name: '@deepseek-ai/dsh-tool-subagent-control'
+
+    - id: tool-subagent-list-agents
+      name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+
+    - id: tool-subagent
+      name: '@deepseek-ai/dsh-tool-subagent'
+      config:
+        provider: spawn
+        toolName: subagent
+        backgroundMode: continuable
+
+    - id: tool-subagent-fork
+      name: '@deepseek-ai/dsh-tool-subagent'
+      config:
+        provider: fork
+        toolName: subagent_fork
+        backgroundMode: continuable
+
+    # Product providers are host-plane singletons. Copy this preset, then
+    # remove `disabled` from either ordinary tool row to expose that product
+    # only to agents composed from the copy.
+    - id: tool-subagent-codex
+      name: '@deepseek-ai/dsh-tool-subagent'
+      disabled: true
+      config:
+        provider: codex
+        toolName: subagent_codex
+        enableRunInBackground: false
+        maxDepth: provider-managed
+
+    - id: tool-subagent-claude-code
+      name: '@deepseek-ai/dsh-tool-subagent'
+      disabled: true
+      config:
+        provider: claude-code
+        toolName: subagent_claude_code
+        enableRunInBackground: false
+        maxDepth: provider-managed
+
+    - id: workflow-workerthread
+      name: '@deepseek-ai/dsh-workflow-workerthread'
+      config:
+        provider: spawn
+
+    - id: tool-workflow
+      name: '@deepseek-ai/dsh-tool-workflow'
+
+    - id: tool-ralph
+      name: '@deepseek-ai/dsh-tool-ralph'
+      config:
+        subagentProvider: spawn
+        maxRounds: 64
+
+# ── remaining model-facing rows ─────────────────────────────────────────────
+
+- id: tool-ask-user
+  name: '@deepseek-ai/dsh-tool-ask-user'
+
+- id: tool-todo
+  name: '@deepseek-ai/dsh-tool-todo'
+  config:
+    allowParallelInProgress: true
+
+# The `web` service and its search provider stay in the host composition; only
+# the model-facing tool is per-session.
+- id: tool-web
+  name: '@deepseek-ai/dsh-tool-web'
+  config:
+    fetch: false
+    searchTimeoutMs: 60000

package/config/agent-presets/standard/preset.yml

@@ -0,0 +1,3 @@
+name: 标准模式
+description: 功能完整的编码 Agent，支持文件编辑、Shell、文件与网页检索、Skills、计划、目标、子代理和工作流。
+order: 1

package/lib/bin.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { loadLayeredEnv } from "@deepseek-ai/dsh-app-boot";
+import { Command, CommanderError } from "commander";
+//#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
+* `@deepseek-ai/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.
+*
+* `web` is a hardcoded alias for `--profile web`; `plugin` manages a profile's
+* plugin dependencies by forwarding to pnpm.
+* @module @deepseek-ai/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];
+/** The launcher's own help text; each app prints its own. */
+const HELP_EXAMPLES = `
+Examples:
+  dsh --profile web                          boot the web profile (same as: dsh web)
+  dsh --profile headless "run the tests"     answer one task, print the result, and exit
+  dsh --profile tui --patch ./extra.yml      boot a custom profile with one extra overlay
+  dsh --profile tui --resume <session>       arguments after the launcher flags reach the app
+  dsh --profile 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 (the root, or the `web` alias).
+* @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.dumpConfig !== true && options.dumpDefaultConfig !== true) return {
+		mode: "profile",
+		profile,
+		patches,
+		args
+	};
+	if (options.dumpConfig === true && options.dumpDefaultConfig === true) program.error("error: --dump-config and --dump-default-config are mutually exclusive");
+	if (args.length > 0) program.error(`error: config dumps take no app arguments, got ${args.map((argument) => JSON.stringify(argument)).join(" ")}`);
+	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,
+		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`.
+* @returns the resolved invocation.
+*/
+function parseDshArgs(argv, version) {
+	let resolved;
+	const program = new Command();
+	program.name("dsh").version(version, "-V, --version", "output the version number").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).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").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-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");
+		resolved = resolveBoot(program, profile, options, args);
+	});
+	/** Reject parent options supplied before a subcommand. */
+	const rejectParentOptions = (command) => {
+		const parent = program.opts();
+		if (parent.profile !== void 0 || parent.patch !== void 0 || parent.dumpConfig !== void 0 || parent.dumpDefaultConfig !== void 0) program.error(`error: ${command} takes none of parent --profile, --patch, --dump-config, or --dump-default-config`);
+	};
+	const web = program.command("web").description("boot the web profile (alias of --profile web); the web app's own flags follow");
+	web.helpOption(false).allowUnknownOption().passThroughOptions().enablePositionalOptions().argument("[args...]", "arguments for the web app (see: dsh web --help)").option("--patch <path>", "extra patch-list overlay applied after the profile layer (repeatable)", collect).option("--dump-config", "print the composed web-profile tree (with the user layer and any --patch) and exit").option("--dump-default-config", "print the web profile's bundle layers (no user layer) and exit").action((args, options) => {
+		rejectParentOptions("web");
+		resolved = resolveBoot(web, "web", options, args);
+	});
+	program.command("plugin").description("manage a profile's plugins by forwarding the remaining arguments to pnpm in the profile directory").requiredOption("--profile <name>", "the profile whose plugins to manage (initialized on first use)").allowUnknownOption().argument("[args...]", "pnpm arguments, forwarded verbatim (add <pkg>, remove <pkg>, why <pkg>, ...)").action((args, options) => {
+		rejectParentOptions("plugin");
+		if (options.profile === "") program.error("error: --profile needs a name");
+		if (args.length === 0) program.error("error: plugin needs pnpm arguments to forward (e.g. add <package>)");
+		resolved = {
+			mode: "plugin",
+			profile: options.profile,
+			args
+		};
+	});
+	try {
+		program.parse(argv, { 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/bin.js
+/**
+* dsh — command-line entry. Dynamic imports per mode keep unrelated modes out
+* of each dispatch path; the adapter prints and exits for
+* `--help`/`--version`/a parse error, so only a valid mode reaches the switch.
+* @module @deepseek-ai/dsh/bin
+*/
+/* v8 ignore file -- built-bin acceptance exercises this self-executing dispatch. */
+/** This app's version, read from its checked-in package.json. */
+function readVersion() {
+	const manifest = JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"));
+	return typeof manifest.version === "string" ? manifest.version : "0.0.0";
+}
+const invocation = parseDshArgs(process.argv.slice(2), readVersion());
+switch (invocation.mode) {
+	case "profile": {
+		const { runProfile } = await import("./profile-boot-T5aOCb6v.js");
+		await runProfile({
+			environment: loadLayeredEnv("dsh"),
+			profile: invocation.profile,
+			patchFiles: invocation.patches,
+			args: invocation.args
+		});
+		break;
+	}
+	case "plugin": {
+		const { runPlugin } = await import("./plugin-Xxr7y7sa.js");
+		process.exit(runPlugin(invocation.profile, invocation.args));
+		break;
+	}
+	case "dump-config": {
+		const { runDumpConfig } = await import("./dump-config-DlxoPVYx.js");
+		runDumpConfig(invocation.profile, invocation.defaultOnly, invocation.patches);
+		break;
+	}
+	default: throw new Error(`dsh: unhandled invocation mode ${JSON.stringify(invocation)}`);
+}
+//#endregion
+export {};

package/lib/dump-config-DlxoPVYx.js

@@ -0,0 +1,57 @@
+import { i as prepareProfile, n as PROFILE_ROOT_FILENAME, r as homePatchPath, s as resolveWindowsShellLayer } from "./profile-boot-DQYCwKII.js";
+import { existsSync } from "node:fs";
+import { loadOptionalPatches, loadOverlayPatches, renderConfigDump } from "@deepseek-ai/dsh-app-boot";
+import { join, resolve } from "node:path";
+//#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 @deepseek-ai/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.
+*/
+function runDumpConfig(profile, defaultOnly, patches) {
+	const loaded = prepareProfile(profile, !defaultOnly);
+	const layers = loaded.layers.map((layer) => ({
+		label: layer.packageName,
+		patches: layer.patches
+	}));
+	const windowsShellLayer = resolveWindowsShellLayer(process.platform, loaded.layers, NAME);
+	if (windowsShellLayer !== void 0) layers.push({
+		label: windowsShellLayer.label,
+		patches: windowsShellLayer.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)
+			});
+		}
+	}
+	process.stdout.write(renderConfigDump(NAME, join(loaded.dir, PROFILE_ROOT_FILENAME), layers));
+}
+/* v8 ignore stop */
+//#endregion
+export { runDumpConfig };