@hominis/fireforge 0.34.2 → 0.36.0

package/dist/src/utils/logger.js

@@ -3,6 +3,19 @@ import * as p from '@clack/prompts';
 import pc from 'picocolors';
 /** Whether verbose mode is enabled */
 let verboseMode = false;
+/**
+ * Whether machine-output mode is active (`--json` / `--raw`).
+ *
+ * In machine mode, stdout belongs EXCLUSIVELY to the machine-readable
+ * payload: all human-facing diagnostics (intro/outro banners, info, warn,
+ * error, steps, notes) are routed to stderr as plain unstyled lines.
+ * Before this mode existed, clack's log helpers wrote styled warnings to
+ * stdout *before* the JSON body — a truncated-directory warning during
+ * `status --json` broke every `JSON.parse(stdout)` consumer, and error
+ * objects on the machine contract were followed by a styled duplicate on
+ * the same stream.
+ */
+let machineOutputMode = false;
 /**
  * Enables or disables verbose mode.
  * @param enabled - Whether to enable verbose output
@@ -10,6 +23,21 @@ let verboseMode = false;
 export function setVerbose(enabled) {
     verboseMode = enabled;
 }
+/**
+ * Switches the logger into (or out of) machine-output mode. Commands with
+ * `--json`/`--raw` flags call this before producing any output.
+ */
+export function setMachineOutputMode(enabled) {
+    machineOutputMode = enabled;
+}
+/** True when machine-output mode is active. */
+export function isMachineOutputMode() {
+    return machineOutputMode;
+}
+/** Writes a plain diagnostic line to stderr (machine-mode side channel). */
+function writeDiagnostic(prefix, message) {
+    process.stderr.write(`${prefix}${message}\n`);
+}
 /**
  * Checks if verbose mode is enabled.
  * @returns True if verbose mode is enabled
@@ -22,43 +50,75 @@ function isVerbose() {
  * @param message - Message to display
  */
 export function verbose(message) {
-    if (isVerbose()) {
-        p.log.info(`[debug] ${message}`);
+    if (!isVerbose())
+        return;
+    if (machineOutputMode) {
+        writeDiagnostic('[debug] ', message);
+        return;
     }
+    p.log.info(`[debug] ${message}`);
 }
 function supportsInteractiveSpinner() {
     return process.stdout.isTTY && process.stderr.isTTY;
 }
 /** Displays the top-level intro banner for a command. */
 export function intro(message) {
+    if (machineOutputMode)
+        return;
     p.intro(message);
 }
 /** Displays the closing outro banner for a command. */
 export function outro(message) {
+    if (machineOutputMode)
+        return;
     p.outro(message);
 }
 /** Logs an informational message. */
 export function info(message) {
+    if (machineOutputMode) {
+        writeDiagnostic('', message);
+        return;
+    }
     p.log.info(message);
 }
 /** Logs a success message. */
 export function success(message) {
+    if (machineOutputMode) {
+        writeDiagnostic('', message);
+        return;
+    }
     p.log.success(message);
 }
 /** Logs a warning message. */
 export function warn(message) {
+    if (machineOutputMode) {
+        writeDiagnostic('warning: ', message);
+        return;
+    }
     p.log.warn(message);
 }
 /** Logs an error message. */
 export function error(message) {
+    if (machineOutputMode) {
+        writeDiagnostic('error: ', message);
+        return;
+    }
     p.log.error(message);
 }
 /** Logs an in-progress step message. */
 export function step(message) {
+    if (machineOutputMode) {
+        writeDiagnostic('', message);
+        return;
+    }
     p.log.step(message);
 }
 /** Logs a plain message without a status prefix. */
 export function message(message) {
+    if (machineOutputMode) {
+        writeDiagnostic('', message);
+        return;
+    }
     p.log.message(message);
 }
 /** Formats text using the success color without logging it. */
@@ -75,6 +135,21 @@ export function formatErrorText(message) {
  * @returns Spinner handle with message(), stop(), and error() methods
  */
 export function spinner(initialMessage) {
+    if (machineOutputMode) {
+        // Spinner progress is diagnostics; keep stdout clean for the payload.
+        return {
+            message: (msg) => {
+                writeDiagnostic('', msg);
+            },
+            stop: (msg) => {
+                if (msg)
+                    writeDiagnostic('', msg);
+            },
+            error: (msg) => {
+                writeDiagnostic('error: ', msg ?? 'Failed');
+            },
+        };
+    }
     if (!supportsInteractiveSpinner()) {
         let latestMessage = initialMessage;
         return {
@@ -107,6 +182,10 @@ export function spinner(initialMessage) {
 }
 /** Emits a cancellation message. */
 export function cancel(message) {
+    if (machineOutputMode) {
+        writeDiagnostic('cancelled: ', message);
+        return;
+    }
     p.cancel(message);
 }
 /** Checks whether a prompt result represents a user cancellation. */
@@ -115,6 +194,9 @@ export function isCancel(value) {
 }
 /** Displays a titled note block for follow-up details. */
 export function note(message, title) {
+    if (machineOutputMode) {
+        writeDiagnostic('', title ? `${title}: ${message}` : message);
+        return;
+    }
     p.note(message, title);
 }
-//# sourceMappingURL=logger.js.map

package/dist/src/utils/options.d.ts

@@ -6,3 +6,18 @@
 export declare function pickDefined<T extends Record<string, unknown>>(obj: T): {
     [K in keyof T]+?: Exclude<T[K], undefined>;
 };
+/**
+ * Wraps an option-argument parser so its failures surface through
+ * commander's own invalid-argument channel.
+ *
+ * Commander only treats errors whose `code` is `'commander.invalidArgument'`
+ * as argument-validation failures; anything else re-throws out of
+ * `parseAsync`, BYPASSING `withErrorHandling` entirely and landing in the
+ * bin's `main().catch` as an unformatted `Fatal error: …` dump with exit 1.
+ * That was the observed behavior for `run --smoke-exit abc` (plain Error),
+ * `test --harness-retries 99` (GeneralError), and `export --order 0`
+ * (FireForge InvalidArgumentError, whose `code` is a numeric ExitCode).
+ * Every `.argParser()`/option-parser callback must be wrapped with this
+ * helper (or throw commander's InvalidArgumentError directly).
+ */
+export declare function commanderArgParser<T>(parse: (raw: string) => T): (raw: string) => T;

package/dist/src/utils/options.js

@@ -13,4 +13,28 @@ export function pickDefined(obj) {
     }
     return result;
 }
-//# sourceMappingURL=options.js.map
+import { InvalidArgumentError as CommanderInvalidArgumentError } from 'commander';
+/**
+ * Wraps an option-argument parser so its failures surface through
+ * commander's own invalid-argument channel.
+ *
+ * Commander only treats errors whose `code` is `'commander.invalidArgument'`
+ * as argument-validation failures; anything else re-throws out of
+ * `parseAsync`, BYPASSING `withErrorHandling` entirely and landing in the
+ * bin's `main().catch` as an unformatted `Fatal error: …` dump with exit 1.
+ * That was the observed behavior for `run --smoke-exit abc` (plain Error),
+ * `test --harness-retries 99` (GeneralError), and `export --order 0`
+ * (FireForge InvalidArgumentError, whose `code` is a numeric ExitCode).
+ * Every `.argParser()`/option-parser callback must be wrapped with this
+ * helper (or throw commander's InvalidArgumentError directly).
+ */
+export function commanderArgParser(parse) {
+    return (raw) => {
+        try {
+            return parse(raw);
+        }
+        catch (error) {
+            throw new CommanderInvalidArgumentError(error instanceof Error ? error.message : String(error));
+        }
+    };
+}

package/dist/src/utils/package-root.js

@@ -34,8 +34,8 @@ export function getPackageRoot() {
     }
     let current = dirname(fileURLToPath(import.meta.url));
     for (;;) {
+        const packagePath = join(current, 'package.json');
         try {
-            const packagePath = join(current, 'package.json');
             const pkg = readPackageMetadata(packagePath);
             if (isFireForgePackageMetadata(pkg)) {
                 cachedPackageRoot = current;
@@ -43,8 +43,16 @@ export function getPackageRoot() {
             }
         }
         catch (error) {
-            void error;
-            // no package.json here — keep walking
+            // Absent package.json: keep walking. A package.json that EXISTS but
+            // fails to parse is a different animal — walking past it could bind
+            // to a wrong ancestor package (any parent exposing bin.fireforge) or
+            // end in the unhelpful generic "could not locate" error, hiding the
+            // actual syntax problem.
+            const code = error.code;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+                throw new Error(`Found ${packagePath} but could not parse it: ` +
+                    (error instanceof Error ? error.message : String(error)), { cause: error });
+            }
         }
         const parent = dirname(current);
         if (parent === current) {
@@ -66,4 +74,3 @@ export function getPackageVersion() {
     const packageRoot = getPackageRoot();
     return readPackageMetadata(join(packageRoot, 'package.json')).version;
 }
-//# sourceMappingURL=package-root.js.map

package/dist/src/utils/parse.js

@@ -212,4 +212,3 @@ export function parseObject(data, label) {
     }
     return new ParsedRecord(data, label);
 }
-//# sourceMappingURL=parse.js.map

package/dist/src/utils/paths.js

@@ -75,4 +75,3 @@ export function toRootRelativePath(root, candidate) {
     }
     return normalizePathSlashes(relative(resolvedRoot, resolvedCandidate));
 }
-//# sourceMappingURL=paths.js.map

package/dist/src/utils/platform.js

@@ -53,4 +53,3 @@ export function isWindows() {
 export function getExecutableExtension() {
     return isWindows() ? '.exe' : '';
 }
-//# sourceMappingURL=platform.js.map

package/dist/src/utils/process.d.ts

@@ -8,6 +8,16 @@ export interface ExecResult {
     stderr: string;
     /** Process exit code */
     exitCode: number;
+    /**
+     * True when `stdout` was cut off at the 50 MB collector cap. Optional so
+     * existing mocks stay valid; absent means "not truncated". Callers that
+     * feed the output into safety decisions (e.g. archive-listing scans) must
+     * treat `true` as a hard failure — a truncated listing looks exactly like
+     * a complete one otherwise.
+     */
+    stdoutTruncated?: boolean;
+    /** True when `stderr` was cut off at the 50 MB collector cap. See {@link ExecResult.stdoutTruncated}. */
+    stderrTruncated?: boolean;
 }
 /**
  * Options for command execution.
@@ -49,6 +59,13 @@ export interface StreamOptions extends ExecOptions {
  * @returns Exit code of the process
  */
 export declare function execStream(command: string, args: string[], options?: StreamOptions): Promise<number>;
+/**
+ * Waits (bounded) for every tracked child process to close. Called by the
+ * bin signal handler after forwarding SIGINT/SIGTERM, so the parent stays
+ * alive long enough for the grace-then-SIGKILL escalation to actually run.
+ * Resolves immediately when no children are active.
+ */
+export declare function waitForActiveChildShutdown(timeoutMs: number): Promise<void>;
 /**
  * Executes a command and inherits stdio (shows output directly).
  *
@@ -81,8 +98,16 @@ export declare function execInheritCapture(command: string, args: string[], opti
 }): Promise<ExecResult>;
 /** Per-line callback for smoke-run stream dispatch. */
 export type SmokeLineCallback = (line: string) => void;
-/** Options for {@link execSmokeRun}. */
-export interface SmokeRunOptions extends ExecOptions {
+/**
+ * Options for {@link execSmokeRun}.
+ *
+ * Deliberately omits `ExecOptions.timeout`: the smoke run's only deadline is
+ * {@link SmokeRunOptions.smokeTimeoutMs}, which signals the whole process
+ * group. Inheriting `timeout` used to be a leaky trap — it was accepted by
+ * the type but silently ignored, so a caller setting it got no deadline at
+ * all.
+ */
+export interface SmokeRunOptions extends Omit<ExecOptions, 'timeout'> {
     /**
      * Hard deadline in milliseconds. When it elapses the child process
      * group is sent SIGTERM and, after `killGraceMs`, SIGKILL. The returned
@@ -138,8 +163,12 @@ export interface SmokeRunResult extends ExecResult {
  * that inherited the group.
  *
  * Windows fallback: `detached: true` does not create an equivalent group
- * there, so we degrade to `child.kill()` and log a best-effort warning
- * via the `onStderrLine` callback if the caller wired one.
+ * there, so we kill the descendant tree with `taskkill /pid <pid> /T /F`
+ * instead. taskkill has no graceful-signal equivalent — both the deadline
+ * and the grace re-invocation are forced kills, so Windows children get
+ * no shutdown window (best-effort; Windows is untested, see README).
+ * `child.kill()` is still sent as a direct-child fallback in case
+ * taskkill itself is unavailable.
  */
 export declare function execSmokeRun(command: string, args: string[], options: SmokeRunOptions): Promise<SmokeRunResult>;
 /**