@cyberselab/command 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# @cyberselab/command
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+对 Payboy 中 Commander 使用范式的封装与约束。项目继续拥有业务命令，包提供 `app → command → action` 的组织方式、延迟加载、配置适配和执行入口。使用原生 Commander，不引入另一套命令树描述语言。
+
+```ts
+// cli/commands/serve.command.ts
+import { defineCommand } from "@cyberselab/command/command";
+
+export const useServeCommand = defineCommand({
+  name: "serve",
+  description: "Start server",
+  loadAction: async () => (await import("../actions/serve.action.js")).serveAction,
+});
+
+// cli/app.ts
+import { createCliApp } from "@cyberselab/command/app";
+const app = createCliApp({
+  name: "example",
+  description: "Example CLI",
+  buildInfo: { version: "0.1.0", branch: "main", commit: "abc" },
+  commands: [useServeCommand],
+});
+
+// main.ts
+import { runCli } from "@cyberselab/command/app";
+process.exitCode = await runCli(app);
+```
+
+`defineCommand()` 返回 `useXxxCommand(app)` 注册函数。`configure(command)` 可声明原生 Commander 参数、选项和别名；`loadAction()` 仅在执行该命令时调用，返回 action 函数。action 收到 `{ args, options, command }`，`args` 按 Commander 声明顺序提供，变长参数作为一个数组；`options` 只包含本命令选项。需要祖先选项时使用 `command.optsWithGlobals()`。
+
+也可以直接编写 `useXxxCommand(app: Command)`，通过 `command` 子路径导入原生 `Command` 类型。命令注册模块应保持轻量，业务依赖只能在 action 执行时导入。
+
+## 配置适配
+
+在 action 中调用 `loadCommandConfig(command, options)`，返回类型由 Schema 推导；或者使用 `withConfig(options, action)` 直接适配原生 `.action()`：
+
+```ts
+import { withConfig } from "@cyberselab/command/config";
+
+app.command("serve").action(withConfig(
+  { appName: "@example/server", schema: serverConfigSchema },
+  async ({ config, options, args, command }) => {
+    const { start } = await import("./actions/start.js");
+    await start(config);
+  },
+));
+```
+
+```sh
+example serve --config ./server.toml --set port=4000
+example create tenant --name demo --set database.pool-size=10
+```
+
+`--config` 与可重复的 `--set path=value` 是保留全局选项，可放在嵌套命令前后；子命令不能重新声明 config / set / help / version 或 `-h` / `-V`。`--set` 保留首个等号之后的完整字符串，支持空值、负数、点号路径和 kebab-case；相同路径最后一次覆盖，标量与对象路径冲突时报错。业务选项不进入配置。`--` 之后保留给 Commander 位置参数。
+
+默认严格拒绝未知选项。`createCliApp({ ..., legacyFlags: true })` 显式启用 Payboy 旧 Flag 兼容模式：已声明选项仍由 Commander 消费，剩余长参数作为配置，例如 `--port=4000`、`--no-cache`。配置覆盖优先级为注入 `options.flags` < 旧 Flag < `--set`。兼容模式不能发现未声明长参数的拼写错误；分离式值沿用旧约定，只消费后续不以 `-` 开头的一个 token，负数请用 `--offset=-1`。配置 Flag 建议放在命令后，避免与子命令位置产生歧义。新项目使用严格模式。
+
+兼容分流针对常规的声明式选项、别名、短选项组合与嵌套命令。不要将其与 `.passThroughOptions()`、外部可执行子命令或自行设置 `.allowUnknownOption()` 混用。需要任意透传时使用严格模式和 `--`，自行在 action 内处理位置参数。
+
+## 执行约定
+
+- 每次运行调用工厂创建新实例。`runCli` 接受的 `argv` 仅包含用户参数，不包含运行时或脚本路径；默认在入口读取 `process.argv.slice(2)`。
+- help / version 不加载配置，也不导入业务 action。构建信息由调用方注入，不读取 git、项目 package.json 或固定前缀环境变量。
+- `runCli` 返回退出码：成功、帮助或版本为 0，输入或配置错误为 2，业务执行失败为 1。库不调用 `process.exit()`，也不修改 `process.exitCode`。
+- stderr 输出经过收敛的错误消息，不整体序列化异常及 cause。可直接调用 action 排查业务异常，或在应用层主动记录经脱敏的诊断。资源清理由应用 action 负责。
+- `stdout` / `stderr` 回调可注入，用于捕获框架输出；业务 action 的输出由项目自身管理。
+
+子路径：`app`、`command`、`config`、`build-info`、`errors`。Bun >= 1.3.14，ESM，暂无 Node.js 支持承诺。

package/dist/app.d.ts

@@ -0,0 +1,18 @@
+import { Command } from "commander";
+import { type BuildInfo } from "./build-info.js";
+export interface CliAppOptions {
+    name: string;
+    description: string;
+    buildInfo?: BuildInfo;
+    legacyFlags?: boolean;
+    commands?: readonly ((app: Command) => unknown)[];
+}
+export declare function createCliApp(options: CliAppOptions): Command;
+export interface RunCliOptions {
+    /** User arguments only: no runtime or script path. */
+    argv?: readonly string[];
+    stdout?: (text: string) => void;
+    stderr?: (text: string) => void;
+}
+/** Returns an exit code. The executable owns process.exitCode and resource cleanup. */
+export declare function runCli(app: Command, options?: RunCliOptions): Promise<number>;

package/dist/app.js

@@ -0,0 +1,72 @@
+import { Command, CommanderError } from "commander";
+import { ConfigError } from "@cyberselab/config/errors";
+import { formatBuildInfo } from "./build-info.js";
+import { CommandInputError } from "./errors.js";
+import { partitionLegacyArguments } from "./arguments.js";
+import { appStates } from "./state.js";
+export function createCliApp(options) {
+    const app = new Command(options.name).description(options.description)
+        .option("--config <path>", "Configuration file path")
+        .option("--set <path=value>", "Override a configuration field (repeatable)", (value, previous = []) => [...previous, value], []);
+    if (options.buildInfo) {
+        const identifier = formatBuildInfo(options.buildInfo);
+        app.version(identifier).addHelpText("beforeAll", `Build: ${identifier}\n`);
+    }
+    appStates.set(app, { legacyFlags: options.legacyFlags ?? false, legacyArguments: [], used: false });
+    for (const register of options.commands ?? [])
+        register(app);
+    return app;
+}
+function configureTree(command, root, out, err) {
+    if (command !== root && command.options.some((option) => ["config", "set", "help", "version"].includes(option.attributeName()) || ["-h", "-V"].includes(option.short ?? ""))) {
+        throw new CommandInputError("Subcommands must not redefine reserved CLI options");
+    }
+    command.exitOverride().configureOutput({
+        writeOut: out, writeErr: err,
+        // Commander input errors can contain raw values. The runner reports a safe diagnostic.
+        outputError: () => { },
+    });
+    for (const child of command.commands)
+        configureTree(child, root, out, err);
+}
+/** Returns an exit code. The executable owns process.exitCode and resource cleanup. */
+export async function runCli(app, options = {}) {
+    const out = options.stdout ?? ((text) => { process.stdout.write(text); });
+    const err = options.stderr ?? ((text) => { process.stderr.write(text); });
+    try {
+        const state = appStates.get(app);
+        if (!state)
+            throw new CommandInputError("Use createCliApp to create the application");
+        if (state.used)
+            throw new CommandInputError("Create a fresh CLI application for each execution");
+        state.used = true;
+        configureTree(app, app, out, err);
+        let argv = [...(options.argv ?? process.argv.slice(2))];
+        if (state.legacyFlags) {
+            const partitioned = partitionLegacyArguments(app, argv);
+            argv = partitioned.argv;
+            state.legacyArguments = partitioned.configurationArgv;
+        }
+        await app.parseAsync(argv, { from: "user" });
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof CommanderError) {
+            if (error.exitCode === 0)
+                return 0;
+            // Help caused by a missing command is an input error, not an execution failure.
+            err("Invalid command line input. Use --help for usage.\n");
+            return 2;
+        }
+        if (error instanceof ConfigError) {
+            err(`${error.code}: ${error.message}\n`);
+            return 2;
+        }
+        if (error instanceof CommandInputError) {
+            err(`${error.message}\n`);
+            return 2;
+        }
+        err("Command execution failed.\n");
+        return 1;
+    }
+}

package/dist/arguments.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+/** Partition only unregistered long flags; Commander retains all business input. */
+export declare function partitionLegacyArguments(root: Command, argv: readonly string[]): {
+    argv: string[];
+    configurationArgv: string[];
+};

package/dist/arguments.js

@@ -0,0 +1,62 @@
+function optionsFor(command) {
+    return [...command.options, ...(command.parent ? optionsFor(command.parent) : [])];
+}
+/** Partition only unregistered long flags; Commander retains all business input. */
+export function partitionLegacyArguments(root, argv) {
+    const output = [];
+    const legacy = [];
+    let command = root;
+    for (let index = 0; index < argv.length; index++) {
+        const token = argv[index];
+        if (token === "--") {
+            output.push(...argv.slice(index));
+            break;
+        }
+        const options = optionsFor(command);
+        const name = token.split("=", 1)[0];
+        const option = options.find((candidate) => candidate.long === name || candidate.short === name);
+        if (option) {
+            output.push(token);
+            if (!token.includes("=") && (option.required || option.optional)) {
+                const next = argv[index + 1];
+                if (next !== undefined && (option.required || !next.startsWith("-")))
+                    output.push(argv[++index]);
+                if (option.variadic) {
+                    while (argv[index + 1] !== undefined && !argv[index + 1].startsWith("-"))
+                        output.push(argv[++index]);
+                }
+            }
+            continue;
+        }
+        // Preserve short clusters, including attached option values, for Commander.
+        if (/^-[^-]/.test(token)) {
+            output.push(token);
+            for (let letter = 1; letter < token.length; letter++) {
+                const short = options.find((candidate) => candidate.short === `-${token[letter]}`);
+                if (short?.required || short?.optional) {
+                    const next = argv[index + 1];
+                    if (letter === token.length - 1 && next !== undefined && (short.required || !next.startsWith("-")))
+                        output.push(argv[++index]);
+                    if (short.variadic) {
+                        while (argv[index + 1] !== undefined && !argv[index + 1].startsWith("-"))
+                            output.push(argv[++index]);
+                    }
+                    break;
+                }
+            }
+            continue;
+        }
+        if (token.startsWith("--") && !["--help", "--version"].includes(name)) {
+            legacy.push(token);
+            if (!token.includes("=") && !token.startsWith("--no-") && argv[index + 1] !== undefined && !argv[index + 1].startsWith("-")) {
+                legacy.push(argv[++index]);
+            }
+            continue;
+        }
+        output.push(token);
+        const child = command.commands.find((candidate) => candidate.name() === token || candidate.aliases().includes(token));
+        if (child)
+            command = child;
+    }
+    return { argv: output, configurationArgv: legacy };
+}

package/dist/build-info.d.ts

@@ -0,0 +1,6 @@
+export interface BuildInfo {
+    version: string;
+    branch?: string;
+    commit?: string;
+}
+export declare function formatBuildInfo(info: BuildInfo): string;

package/dist/build-info.js

@@ -0,0 +1,3 @@
+export function formatBuildInfo(info) {
+    return `${info.version} (${info.branch ?? "unknown"}@${info.commit ?? "unknown"})`;
+}

package/dist/command.d.ts

@@ -0,0 +1,19 @@
+import { Command } from "commander";
+export type CommandOptions = Record<string, unknown>;
+export interface ActionContext<Options extends CommandOptions = CommandOptions> {
+    args: readonly unknown[];
+    options: Options;
+    command: Command;
+}
+export type CommandAction<Options extends CommandOptions = CommandOptions> = (context: ActionContext<Options>) => unknown | Promise<unknown>;
+export declare function getActionContext<Options extends CommandOptions>(values: readonly unknown[]): ActionContext<Options>;
+export interface CommandDefinition<Options extends CommandOptions = CommandOptions> {
+    name: string;
+    description: string;
+    configure?: (command: Command) => void;
+    /** Imported only when the command action actually executes. */
+    loadAction: () => Promise<CommandAction<Options>>;
+}
+/** Produces a useXxxCommand(app) registration function without hiding Commander. */
+export declare function defineCommand<Options extends CommandOptions = CommandOptions>(definition: CommandDefinition<Options>): (app: Command) => Command;
+export type { Command };

package/dist/command.js

@@ -0,0 +1,19 @@
+import { Command } from "commander";
+export function getActionContext(values) {
+    const command = values.at(-1);
+    if (!(command instanceof Command))
+        throw new Error("Expected a Commander action invocation");
+    return { args: values.slice(0, -2), options: command.opts(), command };
+}
+/** Produces a useXxxCommand(app) registration function without hiding Commander. */
+export function defineCommand(definition) {
+    return (app) => {
+        const command = app.command(definition.name).description(definition.description);
+        definition.configure?.(command);
+        command.action(async (...values) => {
+            const action = await definition.loadAction();
+            await action(getActionContext(values));
+        });
+        return command;
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,8 @@
+import { type LoadConfigOptions } from "@cyberselab/config/load";
+import { type ActionContext, type CommandOptions } from "./command.js";
+export type ConfigActionContext<T, Options extends CommandOptions = CommandOptions> = ActionContext<Options> & {
+    config: T;
+};
+export declare function loadCommandConfig<T>(command: ActionContext["command"], options: LoadConfigOptions<T>): Promise<T>;
+/** Adapter for native Commander .action(), with lazy configuration loading. */
+export declare function withConfig<T, Options extends CommandOptions = CommandOptions>(options: LoadConfigOptions<T>, action: (context: ConfigActionContext<T, Options>) => unknown | Promise<unknown>): (...values: unknown[]) => Promise<void>;

package/dist/config.js

@@ -0,0 +1,32 @@
+import { loadConfig } from "@cyberselab/config/load";
+import { ConfigError } from "@cyberselab/config/errors";
+import { readFlagConfig, readSetConfig } from "@cyberselab/config/flags";
+import { mergeConfigRecords } from "@cyberselab/config/record";
+import { getActionContext } from "./command.js";
+import { CommandInputError } from "./errors.js";
+import { appStates, rootCommand } from "./state.js";
+export async function loadCommandConfig(command, options) {
+    const root = rootCommand(command);
+    const global = root.opts();
+    const flags = mergeConfigRecords(mergeConfigRecords(options.flags ?? {}, readFlagConfig(appStates.get(root)?.legacyArguments ?? [])), readSetConfig(global.set ?? []));
+    try {
+        return await loadConfig({
+            ...options,
+            file: { ...options.file, path: global.config ?? options.file?.path },
+            flags,
+        });
+    }
+    catch (error) {
+        if (error instanceof ConfigError)
+            throw error;
+        throw new CommandInputError("Configuration validation failed", error);
+    }
+}
+/** Adapter for native Commander .action(), with lazy configuration loading. */
+export function withConfig(options, action) {
+    return async (...values) => {
+        const context = getActionContext(values);
+        const config = await loadCommandConfig(context.command, options);
+        await action({ ...context, config });
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,3 @@
+export declare class CommandInputError extends Error {
+    constructor(message: string, cause?: unknown);
+}

package/dist/errors.js

@@ -0,0 +1,6 @@
+export class CommandInputError extends Error {
+    constructor(message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "CommandInputError";
+    }
+}

package/dist/state.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from "commander";
+export interface AppState {
+    legacyFlags: boolean;
+    legacyArguments: readonly string[];
+    used: boolean;
+}
+export declare const appStates: WeakMap<Command, AppState>;
+export declare function rootCommand(command: Command): Command;

package/dist/state.js

@@ -0,0 +1,6 @@
+export const appStates = new WeakMap();
+export function rootCommand(command) {
+    while (command.parent !== null)
+        command = command.parent;
+    return command;
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@cyberselab/command",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Payboy conventions for organizing Commander applications, commands and actions",
+  "repository": {
+  "type": "git",
+  "url": "git+https://github.com/Cyberselab/cybersemod.git",
+  "directory": "packages/command"
+},
+"engines": {
+"bun": ">=1.3.14 <2"
+},
+"files": ["src", "dist", "README.md"],
+"exports": {
+  "./app": {
+  "bun": "./src/app.ts",
+  "types": "./dist/app.d.ts",
+  "default": "./dist/app.js"
+},
+"./command": {
+"bun": "./src/command.ts",
+"types": "./dist/command.d.ts",
+"default": "./dist/command.js"
+},
+"./config": {
+"bun": "./src/config.ts",
+"types": "./dist/config.d.ts",
+"default": "./dist/config.js"
+},
+"./build-info": {
+"bun": "./src/build-info.ts",
+"types": "./dist/build-info.d.ts",
+"default": "./dist/build-info.js"
+},
+"./errors": {
+"bun": "./src/errors.ts",
+"types": "./dist/errors.d.ts",
+"default": "./dist/errors.js"
+}
+},
+"scripts": {
+"build": "tsc -p tsconfig.build.json",
+"test": "bun test ./test"
+},
+"dependencies": {
+"@cyberselab/config": "^0.1.0",
+"commander": "^13.1.0"
+}
+}

package/src/app.ts

@@ -0,0 +1,79 @@
+import { Command, CommanderError } from "commander";
+import { ConfigError } from "@cyberselab/config/errors";
+import { formatBuildInfo, type BuildInfo } from "./build-info.js";
+import { CommandInputError } from "./errors.js";
+import { partitionLegacyArguments } from "./arguments.js";
+import { appStates } from "./state.js";
+
+export interface CliAppOptions {
+  name: string;
+  description: string;
+  buildInfo?: BuildInfo;
+  legacyFlags?: boolean;
+  commands?: readonly ((app: Command) => unknown)[];
+}
+
+export function createCliApp(options: CliAppOptions): Command {
+  const app = new Command(options.name).description(options.description)
+    .option("--config <path>", "Configuration file path")
+    .option("--set <path=value>", "Override a configuration field (repeatable)",
+      (value: string, previous: string[] = []) => [...previous, value], [] as string[]);
+  if (options.buildInfo) {
+    const identifier = formatBuildInfo(options.buildInfo);
+    app.version(identifier).addHelpText("beforeAll", `Build: ${identifier}\n`);
+  }
+  appStates.set(app, { legacyFlags: options.legacyFlags ?? false, legacyArguments: [], used: false });
+  for (const register of options.commands ?? []) register(app);
+  return app;
+}
+
+function configureTree(command: Command, root: Command, out: (text: string) => void, err: (text: string) => void): void {
+  if (command !== root && command.options.some((option) => ["config", "set", "help", "version"].includes(option.attributeName()) || ["-h", "-V"].includes(option.short ?? ""))) {
+    throw new CommandInputError("Subcommands must not redefine reserved CLI options");
+  }
+  command.exitOverride().configureOutput({
+    writeOut: out, writeErr: err,
+    // Commander input errors can contain raw values. The runner reports a safe diagnostic.
+    outputError: () => {},
+  });
+  for (const child of command.commands) configureTree(child, root, out, err);
+}
+
+export interface RunCliOptions {
+  /** User arguments only: no runtime or script path. */
+  argv?: readonly string[];
+  stdout?: (text: string) => void;
+  stderr?: (text: string) => void;
+}
+
+/** Returns an exit code. The executable owns process.exitCode and resource cleanup. */
+export async function runCli(app: Command, options: RunCliOptions = {}): Promise<number> {
+  const out = options.stdout ?? ((text: string) => { process.stdout.write(text); });
+  const err = options.stderr ?? ((text: string) => { process.stderr.write(text); });
+  try {
+    const state = appStates.get(app);
+    if (!state) throw new CommandInputError("Use createCliApp to create the application");
+    if (state.used) throw new CommandInputError("Create a fresh CLI application for each execution");
+    state.used = true;
+    configureTree(app, app, out, err);
+    let argv = [...(options.argv ?? process.argv.slice(2))];
+    if (state.legacyFlags) {
+      const partitioned = partitionLegacyArguments(app, argv);
+      argv = partitioned.argv;
+      state.legacyArguments = partitioned.configurationArgv;
+    }
+    await app.parseAsync(argv, { from: "user" });
+    return 0;
+  } catch (error) {
+    if (error instanceof CommanderError) {
+      if (error.exitCode === 0) return 0;
+      // Help caused by a missing command is an input error, not an execution failure.
+      err("Invalid command line input. Use --help for usage.\n");
+      return 2;
+    }
+    if (error instanceof ConfigError) { err(`${error.code}: ${error.message}\n`); return 2; }
+    if (error instanceof CommandInputError) { err(`${error.message}\n`); return 2; }
+    err("Command execution failed.\n");
+    return 1;
+  }
+}

package/src/arguments.ts

@@ -0,0 +1,57 @@
+import type { Command, Option } from "commander";
+
+function optionsFor(command: Command): Option[] {
+  return [...command.options, ...(command.parent ? optionsFor(command.parent) : [])];
+}
+
+/** Partition only unregistered long flags; Commander retains all business input. */
+export function partitionLegacyArguments(root: Command, argv: readonly string[]): { argv: string[]; configurationArgv: string[] } {
+  const output: string[] = [];
+  const legacy: string[] = [];
+  let command = root;
+  for (let index = 0; index < argv.length; index++) {
+    const token = argv[index]!;
+    if (token === "--") { output.push(...argv.slice(index)); break; }
+    const options = optionsFor(command);
+    const name = token.split("=", 1)[0]!;
+    const option = options.find((candidate) => candidate.long === name || candidate.short === name);
+    if (option) {
+      output.push(token);
+      if (!token.includes("=") && (option.required || option.optional)) {
+        const next = argv[index + 1];
+        if (next !== undefined && (option.required || !next.startsWith("-"))) output.push(argv[++index]!);
+        if (option.variadic) {
+          while (argv[index + 1] !== undefined && !argv[index + 1]!.startsWith("-")) output.push(argv[++index]!);
+        }
+      }
+      continue;
+    }
+    // Preserve short clusters, including attached option values, for Commander.
+    if (/^-[^-]/.test(token)) {
+      output.push(token);
+      for (let letter = 1; letter < token.length; letter++) {
+        const short = options.find((candidate) => candidate.short === `-${token[letter]}`);
+        if (short?.required || short?.optional) {
+          const next = argv[index + 1];
+          if (letter === token.length - 1 && next !== undefined && (short.required || !next.startsWith("-"))) output.push(argv[++index]!);
+          if (short.variadic) {
+            while (argv[index + 1] !== undefined && !argv[index + 1]!.startsWith("-")) output.push(argv[++index]!);
+          }
+          break;
+        }
+      }
+      continue;
+    }
+    if (token.startsWith("--") && !["--help", "--version"].includes(name)) {
+      legacy.push(token);
+      if (!token.includes("=") && !token.startsWith("--no-") && argv[index + 1] !== undefined && !argv[index + 1]!.startsWith("-")) {
+        legacy.push(argv[++index]!);
+      }
+      continue;
+    }
+    output.push(token);
+    const child = command.commands.find((candidate) => candidate.name() === token || candidate.aliases().includes(token));
+    if (child) command = child;
+  }
+  return { argv: output, configurationArgv: legacy };
+}

package/src/build-info.ts

@@ -0,0 +1,5 @@
+export interface BuildInfo { version: string; branch?: string; commit?: string }
+
+export function formatBuildInfo(info: BuildInfo): string {
+  return `${info.version} (${info.branch ?? "unknown"}@${info.commit ?? "unknown"})`;
+}

package/src/command.ts

@@ -0,0 +1,39 @@
+import { Command } from "commander";
+
+export type CommandOptions = Record<string, unknown>;
+export interface ActionContext<Options extends CommandOptions = CommandOptions> {
+  args: readonly unknown[];
+  options: Options;
+  command: Command;
+}
+export type CommandAction<Options extends CommandOptions = CommandOptions> = (context: ActionContext<Options>) => unknown | Promise<unknown>;
+
+export function getActionContext<Options extends CommandOptions>(values: readonly unknown[]): ActionContext<Options> {
+  const command = values.at(-1);
+  if (!(command instanceof Command)) throw new Error("Expected a Commander action invocation");
+  return { args: values.slice(0, -2), options: command.opts<Options>(), command };
+}
+
+export interface CommandDefinition<Options extends CommandOptions = CommandOptions> {
+  name: string;
+  description: string;
+  configure?: (command: Command) => void;
+  /** Imported only when the command action actually executes. */
+  loadAction: () => Promise<CommandAction<Options>>;
+}
+
+/** Produces a useXxxCommand(app) registration function without hiding Commander. */
+export function defineCommand<Options extends CommandOptions = CommandOptions>(definition: CommandDefinition<Options>): (app: Command) => Command {
+  return (app) => {
+    const command = app.command(definition.name).description(definition.description);
+    definition.configure?.(command);
+    command.action(async (...values: unknown[]) => {
+      const action = await definition.loadAction();
+      await action(getActionContext<Options>(values));
+    });
+    return command;
+  };
+}
+
+// The native type is intentionally available for project-specific useXxxCommand functions.
+export type { Command };

package/src/config.ts

@@ -0,0 +1,40 @@
+import { loadConfig, type LoadConfigOptions } from "@cyberselab/config/load";
+import { ConfigError } from "@cyberselab/config/errors";
+import { readFlagConfig, readSetConfig } from "@cyberselab/config/flags";
+import { mergeConfigRecords } from "@cyberselab/config/record";
+import { getActionContext, type ActionContext, type CommandOptions } from "./command.js";
+import { CommandInputError } from "./errors.js";
+import { appStates, rootCommand } from "./state.js";
+
+export type ConfigActionContext<T, Options extends CommandOptions = CommandOptions> = ActionContext<Options> & { config: T };
+
+export async function loadCommandConfig<T>(command: ActionContext["command"], options: LoadConfigOptions<T>): Promise<T> {
+  const root = rootCommand(command);
+  const global = root.opts<{ config?: string; set?: string[] }>();
+  const flags = mergeConfigRecords(
+    mergeConfigRecords(options.flags ?? {}, readFlagConfig(appStates.get(root)?.legacyArguments ?? [])),
+    readSetConfig(global.set ?? []),
+  );
+  try {
+    return await loadConfig({
+      ...options,
+      file: { ...options.file, path: global.config ?? options.file?.path },
+      flags,
+    });
+  } catch (error) {
+    if (error instanceof ConfigError) throw error;
+    throw new CommandInputError("Configuration validation failed", error);
+  }
+}
+
+/** Adapter for native Commander .action(), with lazy configuration loading. */
+export function withConfig<T, Options extends CommandOptions = CommandOptions>(
+  options: LoadConfigOptions<T>,
+  action: (context: ConfigActionContext<T, Options>) => unknown | Promise<unknown>,
+): (...values: unknown[]) => Promise<void> {
+  return async (...values) => {
+    const context = getActionContext<Options>(values);
+    const config = await loadCommandConfig(context.command, options);
+    await action({ ...context, config });
+  };
+}

package/src/errors.ts

@@ -0,0 +1,6 @@
+export class CommandInputError extends Error {
+  constructor(message: string, cause?: unknown) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = "CommandInputError";
+  }
+}

package/src/state.ts

@@ -0,0 +1,9 @@
+import type { Command } from "commander";
+
+export interface AppState { legacyFlags: boolean; legacyArguments: readonly string[]; used: boolean }
+export const appStates = new WeakMap<Command, AppState>();
+
+export function rootCommand(command: Command): Command {
+  while (command.parent !== null) command = command.parent;
+  return command;
+}