@hydranium/cli 1.0.0-next.10

package/lib/commands/harness-args.d.ts

@@ -0,0 +1,198 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+/**
+ * The argv machinery the subcommands share, and the error vocabulary they all
+ * speak.
+ *
+ * Its own module rather than functions in the CLI entry point, because the entry
+ * point runs `main()` on import: a test that wants to read an argv the way a
+ * command does would otherwise have to spawn the whole binary, so flag handling
+ * and exit codes could only be covered through a subprocess.
+ *
+ * The messages here are a contract — scripts and CI steps match on them — so
+ * changing one is a breaking change for a caller nobody in this repo can see.
+ *
+ * Every parser takes an `onError` defaulting to report-and-exit, which is what a
+ * command line wants; a caller that would rather handle the problem passes its
+ * own and the parser hands control to it instead of ending the process.
+ *
+ * Each subcommand lives in a sibling `<name>-args` module exporting three things
+ * a test can hold against each other: its flag list, its `--help` text as data,
+ * and the parser that turns an argv into the runner's options. Help that drifts
+ * from the parser is worse than none — it reads as authoritative, so a flag
+ * missing from it is a capability nobody finds, and one it describes but the
+ * parser rejects is an invocation that fails for no visible reason.
+ */
+import type { LogThreshold } from '@hydranium/protocol';
+/**
+ * How a parser reports a usage problem. It never returns, so a parser can treat
+ * the call as a dead end and keep narrowing the value it was about to reject.
+ */
+export type UsageError = (message: string) => never;
+/**
+ * The command-line failure mode: report the usage problem and stop.
+ *
+ * Exit 2, not 1: a CI step that treats "non-zero" as failure is unaffected, but
+ * one that reads 1 as "the workspace has errors" can tell that apart from "I
+ * passed a bad flag" only while the two codes differ. 2 is also what the
+ * bundled heap analyzer exits with for a usage error.
+ */
+export declare function exitWithUsage(message: string): never;
+/** The value flag {@link parseHarnessArgs} consumes itself, before any the subcommand declares. */
+export declare const SERVICES_FLAG = "--services";
+/**
+ * The one spelling of the log threshold, shared by both subcommand families.
+ *
+ * Named rather than repeated because the two families reach the same variable by
+ * different routes — a spawned data-server for one, a spawned driver child for
+ * the other — and a second spelling would make the CLI's verbosity control depend
+ * on which command a caller happened to reach for.
+ */
+export declare const LOG_LEVEL_FLAG = "--log-level";
+/** The value flags {@link parseServerSpawnOptions} consumes itself. */
+export declare const SERVER_SPAWN_VALUE_FLAGS: readonly string[];
+/**
+ * The `--help` line every subcommand describes {@link LOG_LEVEL_FLAG} with.
+ *
+ * Shared text, per-command padding: `command-args.test.ts` compares the flags a
+ * help block DESCRIBES against the flags the parser accepts, and it recognises a
+ * description by the two-space indent — so the line has to be a real option entry
+ * in each block, and the column each block aligns its descriptions at is the
+ * block's own.
+ */
+export declare function logLevelHelpLine(padTo: number): string;
+/**
+ * Narrow a raw {@link LOG_LEVEL_FLAG} value that {@link parseHarnessArgs}
+ * collected, leaving an absent flag absent.
+ *
+ * Throws rather than reaching `onError`, matching {@link parseServerSpawnOptions}:
+ * the level vocabulary belongs to the protocol package, which reports it, and the
+ * entry point's catch turns that into the same message-and-exit.
+ */
+export declare function logLevelOption(value: string | undefined): LogThreshold | undefined;
+/**
+ * Whether the argv asks for the command's help rather than describing a run.
+ *
+ * `valueFlags` are the flags that take a value, and passing them is what makes
+ * the answer correct rather than approximately correct: a token sitting in a
+ * VALUE position is data, not a request. Scanning the whole argv for `--help`
+ * instead means `--content --help` prints help and exits 0 — so a caller writing
+ * that literal text saves nothing and reads success. Omit them only for a
+ * command whose flags take no values at all.
+ */
+export declare function helpRequested(args: readonly string[], valueFlags?: readonly string[]): boolean;
+/**
+ * Print a help block on stdout, not stderr: `<cmd> --help` succeeded, and a
+ * caller piping it into a pager reads the stream a successful command writes to.
+ */
+export declare function printHelp(lines: readonly string[]): void;
+/** What {@link parseHarnessArgs} recovered from an argv. */
+export interface ParsedHarnessArgs {
+    servicesModule: string;
+    /**
+     * An absolute directory path, resolved by {@link resolveWorkspaceArgument} and
+     * checked to exist. `''` when the subcommand declared `requireWorkspace: false`.
+     */
+    workspace: string;
+    /** Value flags by flag name; a bool flag that appeared reads `'true'`. */
+    options: Record<string, string | undefined>;
+    /** Repeatable value flags by flag name, in the order they appeared. */
+    values: Record<string, string[]>;
+}
+/** Per-subcommand deviations from {@link parseHarnessArgs}'s defaults. */
+export interface HarnessArgsConfig {
+    /**
+     * `false` for subcommands that take no workspace: a positional is then
+     * rejected as unexpected, and the returned `workspace` is `''`.
+     */
+    requireWorkspace?: boolean;
+    /**
+     * Value flags that may appear more than once. Each occurrence's value is
+     * collected into `values[flag]` rather than overwriting the single-valued
+     * `options[flag]`.
+     */
+    repeatableValueFlags?: readonly string[];
+    onError?: UsageError;
+}
+/**
+ * Shared parser for the headless-harness subcommands. Consumes the required
+ * `--services <module>` value flag and a single positional `<workspace>`, plus
+ * the `valueFlags` (each takes a value) and `boolFlags` (presence-only, recorded
+ * as `'true'`) the subcommand recognises. Unknown flags or a missing
+ * `--services`/`<workspace>` are usage errors, and so is a `<workspace>` that
+ * reaches no directory — see {@link resolveWorkspaceArgument} for why that cannot
+ * be left to the run.
+ */
+export declare function parseHarnessArgs(args: string[], commandName: string, valueFlags: readonly string[], boolFlags: readonly string[], config?: HarnessArgsConfig): ParsedHarnessArgs;
+/**
+ * Resolve the `<workspace>` positional to an absolute directory path, reporting
+ * a usage error when it reaches anything else.
+ *
+ * The check is here rather than left to the traversal because reaching no
+ * workspace fails NOWHERE downstream: the directory read's `ENOENT` is swallowed
+ * inside a `Promise.all`, the run then reports whatever documents the head
+ * contributes independently of the workspace, and the gate exits 0 — so a CI step
+ * whose path has rotted reads as a clean workspace rather than a broken
+ * invocation. The surviving document count is a property of the head and can be
+ * non-zero, so no caller can use the number as the tell.
+ *
+ * A `file:` URI is converted to a path rather than passed on, because the
+ * headless seams resolve a string workspace as a filesystem path — an
+ * unconverted URI becomes `<cwd>/file:/…` and reaches nothing, by the same silent
+ * route.
+ *
+ * A directory is required: a path naming a file traverses to nothing just as
+ * quietly. An EMPTY directory is accepted — a workspace with no documents
+ * validating clean is an answer, not a bad argument, and the binary is
+ * language-agnostic so it cannot judge whether the files present are the
+ * language's.
+ */
+export declare function resolveWorkspaceArgument(workspace: string, commandName: string, onError?: UsageError): string;
+/** Demand a value the subcommand cannot run without, naming the help that lists it. */
+export declare function assertRequired<T>(value: T | undefined, flag: string, command: string, onError?: UsageError): T;
+/** Parse a numeric CLI option; a usage error on a non-numeric value, `undefined` when absent. */
+export declare function numericOption(value: string | undefined, flag: string, onError?: UsageError): number | undefined;
+/**
+ * Parse the remaining `extra` tokens after {@link parseServerSpawnOptions}
+ * consumed the shared flags. Maps `--<flag>` (kebab) to a `flag` property
+ * (camelCase, leading `--` stripped). Every token must be a recognised flag
+ * followed by its value — unrecognised ones are a usage error, which saves a
+ * silent typo from reading as an omitted option.
+ */
+export declare function parseFlagOptions(extra: string[], commandName: string, recognised: readonly string[], onError?: UsageError): Record<string, string | undefined>;
+/** What {@link parseServerSpawnOptions} recovered from an argv. */
+export interface SpawnOptions {
+    serverCommand: string;
+    serverArgs: string[];
+    cwd?: string;
+    logLevel?: LogThreshold;
+    /** The tokens this parser did not claim, for the subcommand's own options. */
+    extra: string[];
+}
+/**
+ * Shared option parser for subcommands that spawn a data-server child. Consumes
+ * `--server` / `--cwd` / `--log-level` and returns the surviving tokens as
+ * `extra` for {@link parseFlagOptions} to finish.
+ *
+ * An unrecognised `--log-level` value throws rather than reaching `onError`: the
+ * level vocabulary belongs to the protocol package, which reports it, and the
+ * entry point's catch turns that into the same message-and-exit.
+ *
+ * **`--cwd` together with a relative `--server` path is refused, not repaired.**
+ * `--cwd` re-roots the CHILD, so the shell's own reading of `./lib/entry.js` —
+ * relative to where the user stands — is not what the child gets, and the failure
+ * arrives as a bare interpreter module-not-found that names neither flag. Refusing
+ * is the honest half of the choice: re-rooting the token against the parent would
+ * be friendlier for the entry path and would silently change what an argument
+ * meant to be read by the child resolves to, which is the same class of quiet
+ * misdirection one layer along. An absolute path, or dropping `--cwd` and passing
+ * the workspace to the entry, both say what they mean.
+ */
+export declare function parseServerSpawnOptions(args: string[], commandName: string, onError?: UsageError): SpawnOptions;
+//# sourceMappingURL=harness-args.d.ts.map

package/lib/commands/harness-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness-args.d.ts","sourceRoot":"","sources":["../../src/commands/harness-args.ts"],"names":[],"mappings":"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"}

package/lib/commands/harness-args.js

@@ -0,0 +1,339 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { statSync } from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseLogLevelOption } from '../log-level.js';
+/**
+ * The command-line failure mode: report the usage problem and stop.
+ *
+ * Exit 2, not 1: a CI step that treats "non-zero" as failure is unaffected, but
+ * one that reads 1 as "the workspace has errors" can tell that apart from "I
+ * passed a bad flag" only while the two codes differ. 2 is also what the
+ * bundled heap analyzer exits with for a usage error.
+ */
+export function exitWithUsage(message) {
+    console.error(message);
+    process.exit(2);
+}
+/** The value flag {@link parseHarnessArgs} consumes itself, before any the subcommand declares. */
+export const SERVICES_FLAG = '--services';
+/**
+ * The one spelling of the log threshold, shared by both subcommand families.
+ *
+ * Named rather than repeated because the two families reach the same variable by
+ * different routes — a spawned data-server for one, a spawned driver child for
+ * the other — and a second spelling would make the CLI's verbosity control depend
+ * on which command a caller happened to reach for.
+ */
+export const LOG_LEVEL_FLAG = '--log-level';
+/** The value flags {@link parseServerSpawnOptions} consumes itself. */
+export const SERVER_SPAWN_VALUE_FLAGS = ['--server', '--cwd', LOG_LEVEL_FLAG];
+/**
+ * The `--help` line every subcommand describes {@link LOG_LEVEL_FLAG} with.
+ *
+ * Shared text, per-command padding: `command-args.test.ts` compares the flags a
+ * help block DESCRIBES against the flags the parser accepts, and it recognises a
+ * description by the two-space indent — so the line has to be a real option entry
+ * in each block, and the column each block aligns its descriptions at is the
+ * block's own.
+ */
+export function logLevelHelpLine(padTo) {
+    return `  ${`${LOG_LEVEL_FLAG} <lvl>`.padEnd(padTo)}Log threshold for the head this boots (off|error|warn|info|debug|trace).`;
+}
+/**
+ * Narrow a raw {@link LOG_LEVEL_FLAG} value that {@link parseHarnessArgs}
+ * collected, leaving an absent flag absent.
+ *
+ * Throws rather than reaching `onError`, matching {@link parseServerSpawnOptions}:
+ * the level vocabulary belongs to the protocol package, which reports it, and the
+ * entry point's catch turns that into the same message-and-exit.
+ */
+export function logLevelOption(value) {
+    return value === undefined ? undefined : parseLogLevelOption(value);
+}
+/**
+ * Whether the argv asks for the command's help rather than describing a run.
+ *
+ * `valueFlags` are the flags that take a value, and passing them is what makes
+ * the answer correct rather than approximately correct: a token sitting in a
+ * VALUE position is data, not a request. Scanning the whole argv for `--help`
+ * instead means `--content --help` prints help and exits 0 — so a caller writing
+ * that literal text saves nothing and reads success. Omit them only for a
+ * command whose flags take no values at all.
+ */
+export function helpRequested(args, valueFlags = []) {
+    const valueSet = new Set(valueFlags);
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (token === '--help' || token === '-h') {
+            return true;
+        }
+        if (valueSet.has(token)) {
+            index += 1;
+        }
+    }
+    return false;
+}
+/**
+ * Print a help block on stdout, not stderr: `<cmd> --help` succeeded, and a
+ * caller piping it into a pager reads the stream a successful command writes to.
+ */
+export function printHelp(lines) {
+    for (const line of lines) {
+        console.log(line);
+    }
+}
+/**
+ * Shared parser for the headless-harness subcommands. Consumes the required
+ * `--services <module>` value flag and a single positional `<workspace>`, plus
+ * the `valueFlags` (each takes a value) and `boolFlags` (presence-only, recorded
+ * as `'true'`) the subcommand recognises. Unknown flags or a missing
+ * `--services`/`<workspace>` are usage errors, and so is a `<workspace>` that
+ * reaches no directory — see {@link resolveWorkspaceArgument} for why that cannot
+ * be left to the run.
+ */
+export function parseHarnessArgs(args, commandName, valueFlags, boolFlags, config = {}) {
+    const requireWorkspace = config.requireWorkspace ?? true;
+    const onError = config.onError ?? exitWithUsage;
+    const valueSet = new Set(valueFlags);
+    const boolSet = new Set(boolFlags);
+    const repeatableSet = new Set(config.repeatableValueFlags ?? []);
+    const options = {};
+    const values = {};
+    let servicesModule;
+    let workspace;
+    for (let index = 0; index < args.length; index += 1) {
+        const flag = args[index];
+        const next = () => {
+            const value = args[index + 1];
+            if (value === undefined) {
+                onError(`Missing value for ${flag}`);
+            }
+            index += 1;
+            return value;
+        };
+        if (flag === '--services') {
+            servicesModule = next();
+        }
+        else if (boolSet.has(flag)) {
+            options[flag] = 'true';
+        }
+        else if (repeatableSet.has(flag)) {
+            (values[flag] ??= []).push(next());
+        }
+        else if (valueSet.has(flag)) {
+            options[flag] = next();
+        }
+        else if (flag.startsWith('--')) {
+            onError(`Unknown option: ${flag} (hydranium-cli ${commandName} --help)`);
+        }
+        else if (requireWorkspace && workspace === undefined) {
+            workspace = flag;
+        }
+        else {
+            onError(`Unexpected argument: ${flag} (hydranium-cli ${commandName} --help)`);
+        }
+    }
+    return {
+        servicesModule: assertRequired(servicesModule, '--services', commandName, onError),
+        workspace: requireWorkspace
+            ? resolveWorkspaceArgument(assertRequired(workspace, '<workspace>', commandName, onError), commandName, onError)
+            : (workspace ?? ''),
+        options,
+        values
+    };
+}
+/**
+ * Resolve the `<workspace>` positional to an absolute directory path, reporting
+ * a usage error when it reaches anything else.
+ *
+ * The check is here rather than left to the traversal because reaching no
+ * workspace fails NOWHERE downstream: the directory read's `ENOENT` is swallowed
+ * inside a `Promise.all`, the run then reports whatever documents the head
+ * contributes independently of the workspace, and the gate exits 0 — so a CI step
+ * whose path has rotted reads as a clean workspace rather than a broken
+ * invocation. The surviving document count is a property of the head and can be
+ * non-zero, so no caller can use the number as the tell.
+ *
+ * A `file:` URI is converted to a path rather than passed on, because the
+ * headless seams resolve a string workspace as a filesystem path — an
+ * unconverted URI becomes `<cwd>/file:/…` and reaches nothing, by the same silent
+ * route.
+ *
+ * A directory is required: a path naming a file traverses to nothing just as
+ * quietly. An EMPTY directory is accepted — a workspace with no documents
+ * validating clean is an answer, not a bad argument, and the binary is
+ * language-agnostic so it cannot judge whether the files present are the
+ * language's.
+ */
+export function resolveWorkspaceArgument(workspace, commandName, onError = exitWithUsage) {
+    const resolved = toWorkspacePath(workspace, commandName, onError);
+    const help = `(hydranium-cli ${commandName} --help)`;
+    // `throwIfNoEntry: false` suppresses ENOENT and nothing else, so a path the
+    // OS cannot even interrogate still throws raw. A `file://host/share` URI
+    // reaches this on Windows, where it converts to a UNC path rather than
+    // being rejected as unusable, and an unreachable host then surfaces as
+    // `UNKNOWN: unknown error` instead of a usage message naming the argument.
+    let stats;
+    try {
+        stats = statSync(resolved, { throwIfNoEntry: false });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        onError(`<workspace> is not reachable: '${workspace}' resolved to ${resolved} (${detail}) ${help}`);
+    }
+    if (stats === undefined) {
+        onError(`<workspace> does not exist: '${workspace}' resolved to ${resolved}, which is not a path on this machine ${help}`);
+    }
+    if (!stats.isDirectory()) {
+        onError(`<workspace> is not a directory: '${workspace}' resolved to ${resolved}. Pass the directory holding the models ${help}`);
+    }
+    return resolved;
+}
+function toWorkspacePath(workspace, commandName, onError) {
+    if (!/^file:/i.test(workspace)) {
+        return path.resolve(workspace);
+    }
+    try {
+        return fileURLToPath(workspace);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        onError(`<workspace> is not a usable file URI: '${workspace}' (${detail}) (hydranium-cli ${commandName} --help)`);
+    }
+}
+/** Demand a value the subcommand cannot run without, naming the help that lists it. */
+export function assertRequired(value, flag, command, onError = exitWithUsage) {
+    if (value === undefined) {
+        onError(`Missing required option: ${flag} (hydranium-cli ${command} --help)`);
+    }
+    return value;
+}
+/** Parse a numeric CLI option; a usage error on a non-numeric value, `undefined` when absent. */
+export function numericOption(value, flag, onError = exitWithUsage) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) {
+        onError(`Option ${flag} expects a number, got: ${value}`);
+    }
+    return parsed;
+}
+/**
+ * Parse the remaining `extra` tokens after {@link parseServerSpawnOptions}
+ * consumed the shared flags. Maps `--<flag>` (kebab) to a `flag` property
+ * (camelCase, leading `--` stripped). Every token must be a recognised flag
+ * followed by its value — unrecognised ones are a usage error, which saves a
+ * silent typo from reading as an omitted option.
+ */
+export function parseFlagOptions(extra, commandName, recognised, onError = exitWithUsage) {
+    const recognisedSet = new Set(recognised);
+    const out = {};
+    for (let index = 0; index < extra.length; index += 1) {
+        const flag = extra[index];
+        if (!recognisedSet.has(flag)) {
+            onError(`Unknown option: ${flag} (hydranium-cli ${commandName} --help)`);
+        }
+        const value = extra[index + 1];
+        if (value === undefined) {
+            onError(`Missing value for ${flag}`);
+        }
+        out[kebabToCamel(flag.slice(2))] = value;
+        index += 1;
+    }
+    return out;
+}
+function kebabToCamel(name) {
+    return name.replace(/-([a-z])/g, (_, ch) => ch.toUpperCase());
+}
+/**
+ * Whether a `--server` token names a path the shell would resolve against the
+ * working directory.
+ *
+ * Deliberately narrow: only an explicit `./` or `../` prefix, plus a COMMAND
+ * that carries a separator without being absolute. A bare `models` or a
+ * `--stdio` must not match — the point is to recognise the spellings that are
+ * unambiguously filesystem-relative, not to guess which arguments are paths.
+ */
+function isRelativePathToken(token, isCommand) {
+    if (token.startsWith('./') || token.startsWith('../') || token.startsWith('.\\') || token.startsWith('..\\')) {
+        return true;
+    }
+    return isCommand && !path.isAbsolute(token) && /[/\\]/.test(token);
+}
+/**
+ * Shared option parser for subcommands that spawn a data-server child. Consumes
+ * `--server` / `--cwd` / `--log-level` and returns the surviving tokens as
+ * `extra` for {@link parseFlagOptions} to finish.
+ *
+ * An unrecognised `--log-level` value throws rather than reaching `onError`: the
+ * level vocabulary belongs to the protocol package, which reports it, and the
+ * entry point's catch turns that into the same message-and-exit.
+ *
+ * **`--cwd` together with a relative `--server` path is refused, not repaired.**
+ * `--cwd` re-roots the CHILD, so the shell's own reading of `./lib/entry.js` —
+ * relative to where the user stands — is not what the child gets, and the failure
+ * arrives as a bare interpreter module-not-found that names neither flag. Refusing
+ * is the honest half of the choice: re-rooting the token against the parent would
+ * be friendlier for the entry path and would silently change what an argument
+ * meant to be read by the child resolves to, which is the same class of quiet
+ * misdirection one layer along. An absolute path, or dropping `--cwd` and passing
+ * the workspace to the entry, both say what they mean.
+ */
+export function parseServerSpawnOptions(args, commandName, onError = exitWithUsage) {
+    let serverSpec;
+    let cwd;
+    let logLevel;
+    const extra = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const flag = args[index];
+        const claim = () => {
+            const value = args[index + 1];
+            if (value === undefined) {
+                onError(`Missing value for ${flag}`);
+            }
+            index += 1;
+            return value;
+        };
+        if (flag === '--server') {
+            serverSpec = claim();
+        }
+        else if (flag === '--cwd') {
+            cwd = claim();
+        }
+        else if (flag === LOG_LEVEL_FLAG) {
+            logLevel = parseLogLevelOption(claim());
+        }
+        else {
+            extra.push(flag);
+        }
+    }
+    if (!serverSpec) {
+        onError(`Missing required option: --server (hydranium-cli ${commandName} --help)`);
+    }
+    // Split the spec on whitespace — quoting is the caller's shell's job;
+    // by the time we see the value here it's already a single token.
+    const tokens = serverSpec.split(/\s+/).filter(token => token.length > 0);
+    if (tokens.length === 0) {
+        onError('Empty --server value');
+    }
+    const [serverCommand, ...serverArgs] = tokens;
+    if (cwd !== undefined) {
+        const relative = tokens.find((token, position) => isRelativePathToken(token, position === 0));
+        if (relative !== undefined) {
+            onError(`--cwd re-roots the spawned child, so the relative path '${relative}' in --server would be resolved ` +
+                `against '${cwd}' rather than against the current directory. Pass an absolute path, or drop --cwd and ` +
+                `give the workspace to the entry as its own argument (hydranium-cli ${commandName} --help)`);
+        }
+    }
+    return { serverCommand, serverArgs, cwd, logLevel, extra };
+}
+//# sourceMappingURL=harness-args.js.map

package/lib/commands/harness-args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness-args.js","sourceRoot":"","sources":["../../src/commands/harness-args.ts"],"names":[],"mappings":"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"}

package/lib/commands/headless-harness.d.ts

@@ -0,0 +1,97 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import type * as HydraniumCoreNode from '@hydranium/core/node';
+import type { LogThreshold } from '@hydranium/protocol';
+/** The flag every report-producing subcommand names its destination file with. */
+export declare const OUT_FILE_FLAG = "--out-file";
+/** The `@hydranium/core/node` module surface the drivers use (type only). */
+type CoreNodeModule = typeof HydraniumCoreNode;
+/**
+ * The zero-arg service factory a head exports for the headless harness
+ * subcommands (`measure-memory`, `ast-ground-truth`). The head wires its own
+ * filesystem inside.
+ */
+export type ServicesFactory = HydraniumCoreNode.MeasureModelMemoryOptions['createServices'];
+/** What {@link loadHeadlessContext} hands a driver: the head's factory + harness. */
+export interface HeadlessContext {
+    /** The head's zero-arg `createServices(): { shared }` thunk. */
+    createServices: ServicesFactory;
+    /** `@hydranium/core/node`, resolved from the HEAD's dependency graph. */
+    coreNode: CoreNodeModule;
+}
+/**
+ * Child-side: load everything a driver needs from a head's `--services` module —
+ * its `createServices` thunk AND the `@hydranium/core/node` harness, both
+ * resolved from the HEAD's location rather than the CLI's.
+ *
+ * The module is an ESM file (typically a compiled `lib/*.js`) exporting a
+ * ZERO-ARG `createServices(): { shared }`. `hydranium-cli` is language-agnostic
+ * and cannot statically import a head's `create<Lang>Services`, so the dynamic
+ * import is the seam that keeps the binary head-neutral. Resolving the harness
+ * from the head's graph (via `createRequire` rooted at the head module) means the
+ * CLI itself needs no `@hydranium/core` dependency — the head always has it — and
+ * guarantees the harness runs against the SAME core copy as `createServices`.
+ *
+ * Throws a clear error when the path names no file, and when the export is
+ * missing or not a function.
+ */
+export declare function loadHeadlessContext(servicesModule: string): Promise<HeadlessContext>;
+/**
+ * Child-side: deliver a finished report — to `outFile` when one was named, else
+ * to stdout.
+ *
+ * The file is created only once the report EXISTS, which is what the flag buys
+ * over the shell redirection it replaces: `> report.md` truncates the destination
+ * before the command runs, so a head that throws while booting leaves a
+ * zero-length file that a later step reads as an empty report rather than as a
+ * failed run.
+ */
+export declare function emitReport(report: string, outFile: string | undefined): void;
+/**
+ * Parent-side: spawn `node <execArgs...>` inheriting stdio and resolve with the
+ * child's exit code. The harness subcommands need a child process anyway — the
+ * heads' services and a workspace build run in isolation, and `measure-memory`
+ * additionally needs `--expose-gc` for post-GC readings.
+ *
+ * `env` is MERGED over the parent's rather than replacing it: the child resolves
+ * the head's module graph, so dropping `PATH` / `NODE_OPTIONS` / the platform's
+ * own variables would break the import the driver exists to perform.
+ */
+export declare function spawnNodeChild(execArgs: string[], env?: Record<string, string>): Promise<number>;
+/** How a subcommand parent reaches its driver child; the seam `__spawnForTest` replaces. */
+export type SpawnDriverChild = (execArgs: string[], env?: Record<string, string>) => Promise<number>;
+/** What every `--services` subcommand carries for the child it spawns, on top of its own options. */
+export interface DriverSpawnOptions {
+    /**
+     * Log threshold for the head the driver boots. Absent leaves the child's
+     * inherited environment alone, so an ambient `HYDRANIUM_LOG_LEVEL` still wins
+     * where a caller set one.
+     */
+    readonly logLevel?: LogThreshold;
+    /** Test-only: capture the node argv and env instead of spawning the real child. */
+    readonly __spawnForTest?: SpawnDriverChild;
+}
+/**
+ * Parent-side: run a subcommand's driver child and propagate its exit code, so a
+ * shell or CI step sees the gate.
+ *
+ * **The log threshold travels in the child's ENVIRONMENT, not its argv.** The
+ * head's logger reads `HYDRANIUM_LOG_LEVEL` while `createServices` constructs it,
+ * which is inside the driver's dynamic import — a flag the driver parsed would
+ * arrive after the only moment it can be read. Setting it here rather than
+ * exporting it also leaves the CLI's own output alone, unlike an ambient
+ * `HYDRANIUM_LOG_LEVEL=…` the parent would carry too.
+ *
+ * A head that binds a logger of its own decides for itself whether the flag means
+ * anything, which is the intended seam: the CLI is language-agnostic and cannot
+ * reach past `createServices`.
+ */
+export declare function runDriverChild(execArgs: string[], options: DriverSpawnOptions): Promise<void>;
+export {};
+//# sourceMappingURL=headless-harness.d.ts.map

package/lib/commands/headless-harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headless-harness.d.ts","sourceRoot":"","sources":["../../src/commands/headless-harness.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,KAAK,iBAAiB,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AASxD,kFAAkF;AAClF,eAAO,MAAM,aAAa,eAAe,CAAC;AAE1C,6EAA6E;AAC7E,KAAK,cAAc,GAAG,OAAO,iBAAiB,CAAC;AAE/C;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,iBAAiB,CAAC,yBAAyB,CAAC,gBAAgB,CAAC,CAAC;AAE5F,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC7B,gEAAgE;IAChE,cAAc,EAAE,eAAe,CAAC;IAChC,yEAAyE;IACzE,QAAQ,EAAE,cAAc,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,mBAAmB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CA4B1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAS5E;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAShG;AAED,4FAA4F;AAC5F,MAAM,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAErG,qGAAqG;AACrG,MAAM,WAAW,kBAAkB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACjC,mFAAmF;IACnF,QAAQ,CAAC,cAAc,CAAC,EAAE,gBAAgB,CAAC;CAC7C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMnG"}