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

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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
+README.md: 33125014539e801dbd2952a3b4513cafc80bdcee
+README.zh.md: 7ef49a1027d3c17817c9171e1166ed6feecd8559

package/README.md

@@ -15,15 +15,16 @@ An embedding host with no command line provides an empty list; that is the hones
 
 ## 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:
+Any app plugin may inject `cmdlineArgs`, parse it, and publish an ordinary app-owned service. `parseCmdline(ctx, program)` is only a commander adapter; the program's own action owns validation and the published 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)
+  const program = webCommand()
+  program.action(() => ctx.provide('webStartup', webValuesFrom(program)))
+  parseCmdline(ctx, program)
 }
 ```
 
@@ -45,14 +46,12 @@ Every row configured from those values uses ordinary service injection and direc
     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.
+`parseCmdline` refuses at load a program in which no command declares an action, routes every command's exit and output through the launcher (commander copies those settings into subcommands only at registration), and parses the immutable arguments; commander runs the invoked command's synchronous action on success. An action rejects an invalid invocation with `program.error(...)` — before publishing, since statements ahead of the rejection have already run. On `--help`, `--version`, a parse error, or that rejection, the helper writes commander's text and requests exit; 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.

package/README.zh.md

@@ -15,15 +15,16 @@ dsh 启动器交给它所引导应用的那条命令行。启动器只解析属
 
 ## 普通提供方与注入配置
 
-任何应用插件都可以注入 `cmdlineArgs`、解析它，再发布一个普通的应用自有服务。`parseCmdline(ctx, program, plan)` 只适配 commander；返回值与服务都归调用方持有：
+任何应用插件都可以注入 `cmdlineArgs`、解析它，再发布一个普通的应用自有服务。`parseCmdline(ctx, program)` 只适配 commander；校验与发布的服务都归 program 自己的 action 持有：
 
 ```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)
+  const program = webCommand()
+  program.action(() => ctx.provide('webStartup', webValuesFrom(program)))
+  parseCmdline(ctx, program)
 }
 ```
 
@@ -45,14 +46,12 @@ export function apply(ctx: Context): void {
     port: !!js ctx.webStartup.port ?? 3080
 ```
 
-`parseCmdline` 解析不可变参数，再向 `plan` 索取应用自有取值。遇到 `--help`、`--version`、解析错误，或 `plan` 发出的 `program.error(...)` 时，它输出 commander 文本、请求退出并返回 `undefined`；提供方什么也不发布，因此依赖行不会激活。
+`parseCmdline` 在加载时拒绝整棵命令树中没有任何命令声明 action 的 program，把每个命令的退出与输出都接到启动器上（commander 只在注册时把这些设置复制进子命令），再解析不可变参数；解析成功时 commander 运行被调用命令的同步 action。action 用 `program.error(...)` 拒绝无效调用——必须先拒绝后发布，因为写在拒绝之前的语句已经执行。遇到 `--help`、`--version`、解析错误或这种拒绝时，该适配器输出 commander 文本并请求退出；提供方什么也不发布，因此依赖行不会激活。
 
 ### 注入如何排列配置求值
 
 Loader 会把一行的 `!!js` 插值推迟到该行声明的注入全部激活之后，再基于该行的插件上下文求值。所以上例可以直接读取 `ctx.webStartup`：Loader 索取 `webserver` 的配置之前，Cordis 已经填入了这个注入服务。Include 树会保留嵌套表达式节点，直到各个目标行到达这一时点。提供方替换与活动 patch 重载都会针对当前注入服务重新插值，因此启动 flag 不会被悄悄重置。
 
-`enableRow(ctx, id)` 打开某个组合包以禁用状态交付、只有部分调用才需要的行（`dsh web --dev` 及其客户端插件重载链路）。该激活是内存中的覆盖：它不会改写行所配置的 `disabled` 值，并会在已挂载条目的配置重新应用后继续生效。Loader 会对启用后的行应用普通的注入顺序。
-
 ### 共享不可变参数
 
 `get()` 不会消费或修改 argv。多个插件可以解析同一份快照，并分别提供服务。启动器不会检查组合中的命令行所有者；没有读取方的 profile 只会忽略自己的应用参数。

package/lib/index.js

@@ -9,7 +9,8 @@
 * 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
+* provider may publish the parsed values as its own service from its program's
+* commander action, 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.
@@ -34,55 +35,65 @@ const internals = {
 };
 /**
 * 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.
+* program. Commander runs the program's own synchronous action handler on a
+* successful parse; app code there publishes its service and rejects an
+* invalid invocation with `program.error(...)`. 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.
+* Help, version, and rejected arguments — from the grammar or from an action
+* — are terminal for the process: commander writes the text and the helper
+* requests `ctx.appExit`. The action never runs on help, version, or a
+* grammar rejection; an action must reject before it publishes, because
+* statements before its `program.error(...)` have already run.
 * @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.
+* @param program - the app's commander program, with its flags, description,
+* actions, and any subcommands already declared.
+* @throws when the launcher did not provide the command line and exit request,
+* or when no command in the program declares an action.
 */
-function parseCmdline(ctx, program, plan = (() => ({}))) {
+function parseCmdline(ctx, program) {
 	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)
-	});
+	if (!hasAction(program)) throw new Error(`${program.name()}: no command in the program declares an action; parseCmdline runs the invoked command's action on a successful parse, and app code there publishes its service`);
+	configureExitAndOutput(program);
 	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).
+* Whether any command in the tree declares an action handler.
+*
+* The `Command` type cannot express the action precondition, so the handler is
+* read structurally (as {@link isCommanderError} reads commander's control-flow
+* errors): without this guard, a program that forgot its action would parse
+* successfully, publish nothing, and surface only as dependent rows pending on
+* the absent service.
+* @param command - the command whose tree is inspected.
+* @returns true when the command or any registered subcommand has an action.
+*/
+function hasAction(command) {
+	if (typeof command._actionHandler === "function") return true;
+	return command.commands.some(hasAction);
+}
+/**
+* Route every command's exit and output through the launcher adapter.
 *
-* 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.
+* Commander copies `exitOverride` and output configuration into a subcommand
+* only at registration, so a root-only override would let an
+* already-registered subcommand's rejection write to the process streams and
+* call `process.exit` directly, bypassing `ctx.appExit`.
+* @param command - the root of the command tree to configure.
 */
-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();
+function configureExitAndOutput(command) {
+	command.exitOverride().configureOutput({
+		writeOut: (text) => void internals.stdout.write(text),
+		writeErr: (text) => void internals.stderr.write(text)
+	});
+	for (const child of command.commands) configureExitAndOutput(child);
 }
 /**
 * Whether a thrown value is commander's own control-flow error (help, version,
@@ -101,4 +112,4 @@ function isCommanderError(error) {
 	return typeof candidate.code === "string" && candidate.code.startsWith("commander.") && typeof candidate.exitCode === "number";
 }
 //#endregion
-export { enableRow, internals, parseCmdline, provideCmdline };
+export { internals, parseCmdline, provideCmdline };

package/lib/types/index.d.ts

@@ -8,7 +8,8 @@
  * 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
+ * provider may publish the parsed values as its own service from its program's
+ * commander action, 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.
@@ -68,43 +69,23 @@ export declare const internals: {
         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.
+ * program. Commander runs the program's own synchronous action handler on a
+ * successful parse; app code there publishes its service and rejects an
+ * invalid invocation with `program.error(...)`. 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.
+ * Help, version, and rejected arguments — from the grammar or from an action
+ * — are terminal for the process: commander writes the text and the helper
+ * requests `ctx.appExit`. The action never runs on help, version, or a
+ * grammar rejection; an action must reject before it publishes, because
+ * statements before its `program.error(...)` have already run.
  * @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.
+ * @param program - the app's commander program, with its flags, description,
+ * actions, and any subcommands already declared.
+ * @throws when the launcher did not provide the command line and exit request,
+ * or when no command in the program declares an action.
  */
-export declare function enableRow(ctx: Context, id: string): Promise<void>;
+export declare function parseCmdline(ctx: Context, program: Command): void;
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "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",
+  "version": "0.0.1-rc.3",
   "publishConfig": {
     "access": "restricted"
   },
@@ -32,15 +32,15 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.1-rc.1",
     "@deepseek-ai/cordis": "^4.0.1-rc.1",
-    "@deepseek-ai/cordis-plugin-loader": "^1.0.1-rc.1"
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.3"
   },
   "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/dsh-invariants": "^0.0.1-rc.3",
     "@deepseek-ai/cordis": "^4.0.1-rc.1"
   }
 }