@deepseek-ai/dsh-cmdline 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/boot/cmdline/README.md
+README.md: 98335e901bdf8fe33e14c1ad4c1a320d77f30c96
+README.zh.md: 28ea749943c60089c6b4725cb61e121f82aa0114

package/README.md

@@ -0,0 +1,74 @@
+# `@deepseek-ai/dsh-cmdline`
+
+English | [中文](README.zh.md)
+
+The command line a dsh launcher hands to the app it boots. The launcher parses only its own flags (`--profile`, `--patch`, the config dumps) and hands **everything after them** to the tree verbatim, so an app owns its flag family, its `--help` text, and its parse errors instead of the launcher knowing them.
+
+## The launcher values
+
+A launcher calls `provideCmdline(ctx, host)` before any tree entry mounts, which provides:
+
+- `ctx.cmdlineArgs` — the invocation's inner arguments. `get()` is the whole interface, and it returns a snapshot: `dsh --profile tui --resume abc` yields `['--resume', 'abc']`.
+- `ctx.appExit` — a bounded process-exit request, wired to the launcher's shutdown controller.
+
+An embedding host with no command line provides an empty list; that is the honest answer, not a missing value.
+
+## Ordinary providers and injected config
+
+Any app plugin may inject `cmdlineArgs`, parse it, and publish an ordinary app-owned service. `parseCmdline(ctx, program, plan)` is only a commander adapter; the caller owns the returned value and service:
+
+```ts ignore
+export const name = 'web-startup'
+export const inject = ['cmdlineArgs']
+
+export function apply(ctx: Context): void {
+  const values = parseCmdline(ctx, webCommand(), planWebStartup)
+  if (values !== undefined) ctx.provide('webStartup', values)
+}
+```
+
+Its Loader row carries no launcher marker or special kind:
+
+```yaml
+- id: web-startup
+  name: '@deepseek-ai/dsh-web-app/startup'
+```
+
+Every row configured from those values uses ordinary service injection and direct lazy config access:
+
+```yaml
+- id: webserver
+  name: '@deepseek-ai/dsh-host-webserver'
+  inject: [webStartup]
+  config:
+    host: !!js ctx.webStartup.host ?? '127.0.0.1'
+    port: !!js ctx.webStartup.port ?? 3080
+```
+
+`parseCmdline` parses the immutable arguments and asks `plan` for the app-owned value. On `--help`, `--version`, a parse error, or a `program.error(...)` from the plan, it writes commander's text, requests exit, and returns `undefined`; the provider publishes nothing, so dependent rows never activate.
+
+### How injection orders config
+
+Loader defers a row's `!!js` interpolation until that row's declared injections are active, then evaluates against the row's plugin context. The example above can therefore read `ctx.webStartup` directly: Cordis has already populated that injected service before Loader asks for `webserver`'s config. Include trees preserve nested expression nodes until each target row reaches this point. Provider replacement and live patch reload repeat interpolation against the current injected services, so a launch flag cannot be silently reset.
+
+`enableRow(ctx, id)` turns on a row a bundle ships disabled because only some invocations want it (`dsh web --dev` and its client-plugin reload chain). The activation is an in-memory override: it does not rewrite the row's configured `disabled` value and survives config reapplication for that mounted entry. Loader applies the enabled row's ordinary injection ordering.
+
+### Shared immutable arguments
+
+`get()` does not consume or mutate argv. Multiple plugins can parse the same snapshot and independently provide services. The launcher does not inspect the composition for a command-line owner; a profile with no reader simply ignores its app arguments.
+
+An out-of-tree plugin brings its own commander copy, so commander's control-flow errors are detected structurally rather than by class identity; an identity check would rethrow a printed help as a fatal load failure.
+
+## Model Experience
+
+None, as this package resolves the process's own command line before any session exists.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Launcher flags must precede app arguments.** The split is positional: the first token the launcher does not recognize starts the inner arguments, so `--patch` placed after an app flag belongs to the app. The launcher's parser consumes one `--`, so an app argument that must survive as a literal `--` needs `-- --`.
+- **An app-owned service has no statically declared provider.** Consumer rows name it through ordinary injection; a bundle that omits its provider fails at settlement with pending entries naming the service rather than at load.
+- **A user patch that replaces a row's whole `config` drops its expressions.** A flag beats the value written beside it, not a literal a user wrote in place of the expression; keeping the expression is what keeps the flag winning.

package/README.zh.md

@@ -0,0 +1,74 @@
+# `@deepseek-ai/dsh-cmdline`
+
+[English](README.md) | 中文
+
+dsh 启动器交给它所引导应用的那条命令行。启动器只解析属于自己的 flag（`--profile`、`--patch`、配置 dump），并把**其后的一切**原样交给配置树，因此 flag 家族、`--help` 文本和解析错误都由应用自己持有，启动器不必知道它们。
+
+## 启动器提供的值
+
+启动器在任何配置树条目挂载之前调用 `provideCmdline(ctx, host)`，它提供：
+
+- `ctx.cmdlineArgs`：本次调用的内层参数。`get()` 就是它的全部接口，返回一份快照：`dsh --profile tui --resume abc` 得到 `['--resume', 'abc']`。
+- `ctx.appExit`：一个有边界的进程退出请求，接到启动器的关停控制器上。
+
+没有命令行的嵌入宿主提供空列表；这是诚实的答案，而不是缺失的值。
+
+## 普通提供方与注入配置
+
+任何应用插件都可以注入 `cmdlineArgs`、解析它，再发布一个普通的应用自有服务。`parseCmdline(ctx, program, plan)` 只适配 commander；返回值与服务都归调用方持有：
+
+```ts ignore
+export const name = 'web-startup'
+export const inject = ['cmdlineArgs']
+
+export function apply(ctx: Context): void {
+  const values = parseCmdline(ctx, webCommand(), planWebStartup)
+  if (values !== undefined) ctx.provide('webStartup', values)
+}
+```
+
+它的 Loader 行不携带启动器标记，也没有特殊类型：
+
+```yaml
+- id: web-startup
+  name: '@deepseek-ai/dsh-web-app/startup'
+```
+
+所有由这些取值配置的行都使用普通服务注入，并在惰性配置中直接访问该服务：
+
+```yaml
+- id: webserver
+  name: '@deepseek-ai/dsh-host-webserver'
+  inject: [webStartup]
+  config:
+    host: !!js ctx.webStartup.host ?? '127.0.0.1'
+    port: !!js ctx.webStartup.port ?? 3080
+```
+
+`parseCmdline` 解析不可变参数，再向 `plan` 索取应用自有取值。遇到 `--help`、`--version`、解析错误，或 `plan` 发出的 `program.error(...)` 时，它输出 commander 文本、请求退出并返回 `undefined`；提供方什么也不发布，因此依赖行不会激活。
+
+### 注入如何排列配置求值
+
+Loader 会把一行的 `!!js` 插值推迟到该行声明的注入全部激活之后，再基于该行的插件上下文求值。所以上例可以直接读取 `ctx.webStartup`：Loader 索取 `webserver` 的配置之前，Cordis 已经填入了这个注入服务。Include 树会保留嵌套表达式节点，直到各个目标行到达这一时点。提供方替换与活动 patch 重载都会针对当前注入服务重新插值，因此启动 flag 不会被悄悄重置。
+
+`enableRow(ctx, id)` 打开某个组合包以禁用状态交付、只有部分调用才需要的行（`dsh web --dev` 及其客户端插件重载链路）。该激活是内存中的覆盖：它不会改写行所配置的 `disabled` 值，并会在已挂载条目的配置重新应用后继续生效。Loader 会对启用后的行应用普通的注入顺序。
+
+### 共享不可变参数
+
+`get()` 不会消费或修改 argv。多个插件可以解析同一份快照，并分别提供服务。启动器不会检查组合中的命令行所有者；没有读取方的 profile 只会忽略自己的应用参数。
+
+树外插件会带来自己的一份 commander 副本，因此 commander 的控制流错误按结构识别，而不是按类身份识别；按身份判断会把已经打印出来的 help 重新抛成致命的加载失败。
+
+## 模型体验
+
+无。本包在任何会话存在之前解析进程自身的命令行。
+
+#### KV Cache 影响
+
+无；本包既不组装也不发送提供方请求。
+
+## 已知限制与延期工作
+
+- **启动器的 flag 必须写在应用参数之前**：切分按位置进行，启动器不认识的第一个 token 就是内层参数的起点，因此写在某个应用 flag 之后的 `--patch` 属于应用。启动器的解析器会消耗掉一个 `--`，因此必须以字面量 `--` 存活到应用的参数需要写成 `-- --`。
+- **应用自有服务没有静态声明的提供方**：消费行通过普通注入点名它；缺少提供方的组合包会在结算时失败，由待处理条目点名该服务，而不是在加载时失败。
+- **用户 patch 若整体替换某行的 `config`，会连同其中的表达式一起丢掉**：flag 胜过的是表达式旁写着的那个值，而不是用户用字面量替换掉表达式之后的结果；保留表达式才能保留 flag 的优先级。

package/lib/index.js

@@ -0,0 +1,104 @@
+//#region lib/types/index.js
+/**
+* @deepseek-ai/dsh-cmdline — the command line a dsh launcher hands to the app
+* it boots.
+*
+* The launcher parses only its own flags (`--profile`, `--patch`, the config
+* dumps) and hands everything after them to the tree verbatim through the
+* {@link CmdlineArgs} service, so an app owns its flag family, its `--help`
+* text, and its parse errors instead of the launcher knowing them.
+*
+* Any app plugin can inject `cmdlineArgs` and call {@link parseCmdline}. A
+* provider may publish the parsed values as its own service, and ordinary rows
+* can inject that service and read it from lazily resolved config —
+* `port: !!js ctx.webStartup.port ?? 3080` — so a flag beats the value written
+* beside it. No row has launcher-level command-line status.
+* @module @deepseek-ai/dsh-cmdline
+*/
+/**
+* Provide the command line and the exit request on a host context before any
+* tree entry mounts. Both are launcher facts, not config: an embedding host
+* with no command line provides an empty argument list.
+* @param ctx - the host context the tree will mount under.
+* @param host - the invocation's arguments and its exit request.
+*/
+function provideCmdline(ctx, host) {
+	const snapshot = Object.freeze([...host.args]);
+	ctx.provide("cmdlineArgs", { get: () => snapshot });
+	ctx.provide("appExit", host.exit);
+}
+/** The process streams commander output is written to; production writes to the process. */
+const internals = {
+	stdout: process.stdout,
+	stderr: process.stderr
+};
+/**
+* Parse the launcher's immutable argument snapshot with an app's commander
+* program. The caller decides whether and how to publish the returned value;
+* this helper has no Loader-row or service ownership semantics.
+*
+* Help, version, and rejected arguments are terminal for the process: commander
+* writes the text, the helper requests `ctx.appExit`, and it returns
+* `undefined` so the caller publishes nothing.
+* @param ctx - plugin context carrying `cmdlineArgs` and `appExit`.
+* @param program - the app's commander program, with its flags and description already declared.
+* @param plan - this invocation's resolved value; omitted returns an empty object.
+* @returns the resolved value, or `undefined` when the app asked to exit.
+* @throws when the launcher did not provide the command line and exit request.
+*/
+function parseCmdline(ctx, program, plan = (() => ({}))) {
+	const args = ctx.get("cmdlineArgs");
+	const exit = ctx.get("appExit");
+	if (args === void 0 || exit === void 0) throw new Error(`${program.name()}: the launcher must provide ctx.cmdlineArgs and ctx.appExit before the tree mounts`);
+	program.exitOverride().configureOutput({
+		writeOut: (text) => void internals.stdout.write(text),
+		writeErr: (text) => void internals.stderr.write(text)
+	});
+	try {
+		program.parse(args.get(), { from: "user" });
+		return plan(program, ctx);
+	} catch (error) {
+		if (!isCommanderError(error)) throw error;
+		exit(error.exitCode);
+		return;
+	}
+}
+/**
+* Turn on a row this composition ships disabled, because this invocation asked
+* for it (`dsh web --dev` and its client-plugin reload chain).
+*
+* A row cannot be inserted from inside a mounting plugin — the Loader returns a
+* prefixed id it then fails to resolve — so a conditional row ships disabled
+* and a row mounted beside it enables it after startup resolves the invocation.
+* The Loader keeps that activation in memory, separate from serialized options,
+* so reapplying the composition cannot restore the invocation's row to disabled.
+* @param ctx - plugin context whose Loader tree carries the row.
+* @param id - the row id.
+* @returns nothing once the row has started or is waiting for its dependencies.
+* @throws when the Loader or named row is absent.
+*/
+async function enableRow(ctx, id) {
+	const loader = ctx.get("loader");
+	if (loader === void 0) throw new Error("dsh-cmdline: enabling a row requires the Loader service");
+	const entry = [...loader.entries()].find((candidate) => candidate.options.id === id);
+	if (entry === void 0) throw new Error(`dsh-cmdline: the composition has no ${JSON.stringify(id)} row to enable`);
+	await entry.enableRuntime();
+}
+/**
+* Whether a thrown value is commander's own control-flow error (help, version,
+* a parse error, or `program.error`).
+*
+* Detected structurally, not with `instanceof`: an out-of-tree plugin brings
+* its own commander copy, whose `CommanderError` class is a different identity
+* from this package's, and an identity check there would rethrow a printed
+* help as a fatal load failure.
+* @param error - the thrown value.
+* @returns true when the value carries commander's error code and exit code.
+*/
+function isCommanderError(error) {
+	if (typeof error !== "object" || error === null) return false;
+	const candidate = error;
+	return typeof candidate.code === "string" && candidate.code.startsWith("commander.") && typeof candidate.exitCode === "number";
+}
+//#endregion
+export { enableRow, internals, parseCmdline, provideCmdline };

package/lib/invariant.js

@@ -0,0 +1,25 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-cmdline`.
+* @module @deepseek-ai/dsh-cmdline/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-cmdline";
+/** Cordis companion plugin name. */
+const name = "cmdline-invariant";
+/** Service required before the companion can register. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: `cmdlineArgs` is an immutable launcher fact that any
+* number of ordinary plugins may read. App-owned providers and consumers use
+* normal Cordis service injection, whose missing dependencies are already
+* reported by Loader settlement.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @deepseek-ai/dsh-cmdline — the command line a dsh launcher hands to the app
+ * it boots.
+ *
+ * The launcher parses only its own flags (`--profile`, `--patch`, the config
+ * dumps) and hands everything after them to the tree verbatim through the
+ * {@link CmdlineArgs} service, so an app owns its flag family, its `--help`
+ * text, and its parse errors instead of the launcher knowing them.
+ *
+ * Any app plugin can inject `cmdlineArgs` and call {@link parseCmdline}. A
+ * provider may publish the parsed values as its own service, and ordinary rows
+ * can inject that service and read it from lazily resolved config —
+ * `port: !!js ctx.webStartup.port ?? 3080` — so a flag beats the value written
+ * beside it. No row has launcher-level command-line status.
+ * @module @deepseek-ai/dsh-cmdline
+ */
+import type { Command } from 'commander';
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * The invocation's inner arguments: everything after the launcher's own flags,
+ * verbatim and in argv order. `dsh --profile tui --resume abc` yields
+ * `['--resume', 'abc']`.
+ */
+export interface CmdlineArgs {
+    /**
+     * Read the inner arguments.
+     * @returns the arguments in argv order; empty when the invocation carried none.
+     */
+    get(): readonly string[];
+}
+/** Request bounded process exit; the launcher wires it to its shutdown controller. */
+export interface AppExit {
+    /**
+     * Request exit once the tree has been disposed.
+     * @param code - the process exit code.
+     */
+    (code: number): void;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** The invocation's inner arguments; provided by a launcher before the tree mounts. */
+        cmdlineArgs?: CmdlineArgs;
+        /** Bounded process-exit request; provided by a launcher before the tree mounts. */
+        appExit?: AppExit;
+    }
+}
+/** The launcher facts an app needs. */
+export interface CmdlineHost {
+    /** The invocation's inner arguments, in argv order. */
+    args: readonly string[];
+    /** Bounded process-exit request. */
+    exit: AppExit;
+}
+/**
+ * Provide the command line and the exit request on a host context before any
+ * tree entry mounts. Both are launcher facts, not config: an embedding host
+ * with no command line provides an empty argument list.
+ * @param ctx - the host context the tree will mount under.
+ * @param host - the invocation's arguments and its exit request.
+ */
+export declare function provideCmdline(ctx: Context, host: CmdlineHost): void;
+/** The process streams commander output is written to; production writes to the process. */
+export declare const internals: {
+    stdout: {
+        write(chunk: string): unknown;
+    };
+    stderr: {
+        write(chunk: string): unknown;
+    };
+};
+/**
+ * Resolve parsed arguments into an app-owned value. Call
+ * `program.error(...)` to reject the invocation with a usage message instead
+ * of throwing.
+ * @param program - the parsed commander program.
+ * @param ctx - the plugin context that received the command line.
+ * @returns the value an ordinary provider plugin may publish.
+ */
+export type CmdlinePlan<T = unknown> = (program: Command, ctx: Context) => T;
+/**
+ * Parse the launcher's immutable argument snapshot with an app's commander
+ * program. The caller decides whether and how to publish the returned value;
+ * this helper has no Loader-row or service ownership semantics.
+ *
+ * Help, version, and rejected arguments are terminal for the process: commander
+ * writes the text, the helper requests `ctx.appExit`, and it returns
+ * `undefined` so the caller publishes nothing.
+ * @param ctx - plugin context carrying `cmdlineArgs` and `appExit`.
+ * @param program - the app's commander program, with its flags and description already declared.
+ * @param plan - this invocation's resolved value; omitted returns an empty object.
+ * @returns the resolved value, or `undefined` when the app asked to exit.
+ * @throws when the launcher did not provide the command line and exit request.
+ */
+export declare function parseCmdline<T>(ctx: Context, program: Command, plan?: CmdlinePlan<T>): T | undefined;
+/**
+ * Turn on a row this composition ships disabled, because this invocation asked
+ * for it (`dsh web --dev` and its client-plugin reload chain).
+ *
+ * A row cannot be inserted from inside a mounting plugin — the Loader returns a
+ * prefixed id it then fails to resolve — so a conditional row ships disabled
+ * and a row mounted beside it enables it after startup resolves the invocation.
+ * The Loader keeps that activation in memory, separate from serialized options,
+ * so reapplying the composition cannot restore the invocation's row to disabled.
+ * @param ctx - plugin context whose Loader tree carries the row.
+ * @param id - the row id.
+ * @returns nothing once the row has started or is waiting for its dependencies.
+ * @throws when the Loader or named row is absent.
+ */
+export declare function enableRow(ctx: Context, id: string): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-cmdline`.
+ * @module @deepseek-ai/dsh-cmdline/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "cmdline-invariant";
+/** Service required before the companion can register. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@deepseek-ai/dsh-cmdline",
+  "description": "Immutable command-line handoff from a dsh launcher to any app plugin that injects cmdlineArgs",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/boot/cmdline"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.1-rc.1"
+  },
+  "devDependencies": {
+    "commander": "^15.0.0",
+    "@deepseek-ai/cordis-plugin-include": "^1.0.5-rc.1",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}