@hydraharness/harness-cmdline 0.0.0-stage → 0.1.1-rc.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# `@hydraharness/harness-cmdline`
 
-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.
+The command line a hydra 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: `hydra --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)` 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 program = webCommand()
+  program.action(() => ctx.provide('webStartup', webValuesFrom(program)))
+  parseCmdline(ctx, program)
+}
+```
+
+Its Loader row carries no launcher marker or special kind:
+
+```yaml
+- id: web-startup
+  name: '@hydraharness/harness-web-app/startup'
+```
+
+Every row configured from those values uses ordinary service injection and direct lazy config access:
+
+```yaml
+- id: webserver
+  name: '@hydraharness/harness-host-webserver'
+  inject: [webStartup]
+  config:
+    host: !!js ctx.webStartup.host ?? '127.0.0.1'
+    port: !!js ctx.webStartup.port ?? 3080
+```
+
+`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.
+
+### 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/lib/index.js

@@ -0,0 +1,115 @@
+//#region lib/types/index.js
+/**
+* @hydraharness/harness-cmdline — the command line a hydra 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 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.
+* @module @hydraharness/harness-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. 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 — 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, 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) {
+	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`);
+	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" });
+	} catch (error) {
+		if (!isCommanderError(error)) throw error;
+		exit(error.exitCode);
+	}
+}
+/**
+* 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`).
+*
+* 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 { internals, parseCmdline, provideCmdline };

package/lib/invariant.js

@@ -0,0 +1,25 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-cmdline`.
+* @module @hydraharness/harness-cmdline/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-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,91 @@
+/**
+ * @hydraharness/harness-cmdline — the command line a hydra 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 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.
+ * @module @hydraharness/harness-cmdline
+ */
+import type { Command } from 'commander';
+import type { Context } from '@hydraharness/cordis';
+/**
+ * The invocation's inner arguments: everything after the launcher's own flags,
+ * verbatim and in argv order. `hydra --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 '@hydraharness/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;
+    };
+};
+/**
+ * Parse the launcher's immutable argument snapshot with an app's commander
+ * 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 — 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, 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(ctx: Context, program: Command): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-cmdline`.
+ * @module @hydraharness/harness-cmdline/invariant
+ */
+import type { Context } from '@hydraharness/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

@@ -1,6 +1,46 @@
 {
   "name": "@hydraharness/harness-cmdline",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Immutable command-line handoff from a hydra launcher to any app plugin that injects cmdlineArgs",
+  "version": "0.1.1-rc.7",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-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": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.7",
+    "@hydraharness/cordis-plugin-loader": "^1.0.3",
+    "@hydraharness/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "commander": "^15.0.0",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.7",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/cordis-plugin-include": "^1.0.7",
+    "@hydraharness/cordis-plugin-loader": "^1.0.3"
+  }
 }