@deepseek-ai/dsh-cmdline 0.0.1-rc.2 → 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: 2e8e58b23785fa78bd2663a459817669309a81be
-README.zh.md: c04d76905edb4afa6b18b36b8284b14990be6bdd
+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,7 +46,7 @@ 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
 

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,7 +46,7 @@ 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 文本并请求退出；提供方什么也不发布，因此依赖行不会激活。
 
 ### 注入如何排列配置求值
 

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,36 +35,67 @@ 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;
 	}
 }
 /**
+* 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.
+*
+* 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.
+*/
+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,
 * a parse error, or `program.error`).
 *

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,28 +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.
+ * @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 parseCmdline<T>(ctx: Context, program: Command, plan?: CmdlinePlan<T>): T | undefined;
+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.2",
+  "version": "0.0.1-rc.3",
   "publishConfig": {
     "access": "restricted"
   },
@@ -33,14 +33,14 @@
   "license": "BSD-3-Clause",
   "peerDependencies": {
     "@deepseek-ai/cordis-plugin-loader": "^1.0.1-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+    "@deepseek-ai/cordis": "^4.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.2",
-    "@deepseek-ai/cordis": "^4.0.1-rc.1",
-    "@deepseek-ai/cordis-plugin-include": "^1.0.5-rc.1"
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.3",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
   }
 }