@memberjunction/cli-core 6.1.0-edge.3 → 6.1.0-edge.5

package/dist/base-cli-plugin.d.ts

@@ -1,5 +1,5 @@
 import { Command } from '@oclif/core';
-import type { IMJCLIRuntimeHost, MJCLIResult, PluginUsage } from './types.js';
+import { type IMJCLIRuntimeHost, type MJCLIResult, type PluginUsage } from './types.js';
 /**
  * Abstract base for every pluggable `mj` command (plan D1/D2).
  *
@@ -9,9 +9,19 @@ import type { IMJCLIRuntimeHost, MJCLIResult, PluginUsage } from './types.js';
  * shared {@link BaseCLIPlugin.run} wires up the {@link IMJCLIRuntimeHost}, emits
  * the runtime advisory, renders the result per `--format`, and sets the exit code.
  *
- * The global flags `--format`, `--verbose`, and `--no-banner` are declared on
- * {@link BaseCLIPlugin.baseFlags} and inherited by every subclass via oclif's
- * native `baseFlags` merging — no per-command duplication (plan D3).
+ * The global flags `--format`, `--verbose`, `--no-banner`, and `--interactive`
+ * are declared on {@link BaseCLIPlugin.baseFlags} and inherited by every subclass
+ * via oclif's native `baseFlags` merging — no per-command duplication (plan D3).
+ *
+ * Two defaults are inferred here rather than declared per command, so that a human
+ * and an agent each get the right behaviour without either having to ask for it:
+ * - **Format follows the pipe.** With no explicit `--format`, a non-TTY stdout
+ *   resolves to `json`. A caller that redirected stdout has already said it is a
+ *   machine; it should not also have to remember a flag.
+ * - **Prompting follows the terminal.** {@link BaseCLIPlugin.Interactive} is true at a
+ *   real terminal and false when piped, spawned, or running in CI. A
+ *   {@link NonInteractiveError} escaping `Execute` is rendered as a structured,
+ *   actionable result rather than a stack trace.
  */
 export declare abstract class BaseCLIPlugin extends Command {
     /** Inherited by every subclass through oclif's static `baseFlags` mechanism. */
@@ -19,6 +29,7 @@ export declare abstract class BaseCLIPlugin extends Command {
         format: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
         verbose: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         'no-banner': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        interactive: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
     /**
      * Every plugin declares its own usage + runtime metadata. The CLI root reads
@@ -28,6 +39,13 @@ export declare abstract class BaseCLIPlugin extends Command {
      */
     static Usage: PluginUsage;
     protected Host: IMJCLIRuntimeHost;
+    /**
+     * Whether this run may prompt — detected from the terminal unless `--interactive` /
+     * `--no-interactive` says otherwise. Subclasses pass this into `ResolveOrPrompt`
+     * rather than calling `@inquirer` directly, so a missing value fails fast with the
+     * flag to pass instead of blocking on stdin.
+     */
+    protected Interactive: boolean;
     /** Parsed flags, captured once in {@link run}; read via {@link GetFlags}. */
     private parsedFlags;
     /**
@@ -45,6 +63,14 @@ export declare abstract class BaseCLIPlugin extends Command {
      * oclif entry point — do NOT override in subclasses. Override {@link Execute}.
      */
     run(): Promise<void>;
+    /**
+     * Runs {@link BaseCLIPlugin.Execute}, converting a {@link NonInteractiveError} into a
+     * normal failed result. A command that asked for a value it wasn't given has NOT
+     * crashed — it has a precise, recoverable complaint, and an agent gets far more from
+     * `{code:'E_NON_INTERACTIVE', suggestion:'Pass --entity …'}` than from a stack trace.
+     * Every other error keeps propagating to oclif untouched.
+     */
+    private RunExecute;
     /**
      * Optional post-Emit hook. Override to release resources (DB pools, singletons)
      * and, when necessary, `process.exit()` to terminate lingering background work.

package/dist/base-cli-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-cli-plugin.d.ts","sourceRoot":"","sources":["../src/base-cli-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAS,MAAM,aAAa,CAAC;AAE7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAgB,WAAW,EAAE,MAAM,SAAS,CAAC;AAEzF;;;;;;;;;;;;GAYG;AACH,8BAAsB,aAAc,SAAQ,OAAO;IACjD,gFAAgF;IAChF,OAAgB,SAAS;;;;MAQvB;IAEF;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC;IAE1B,SAAS,CAAC,IAAI,EAAG,iBAAiB,CAAC;IAEnC,6EAA6E;IAC7E,OAAO,CAAC,WAAW,CAAU;IAE7B;;;;;;;;;OASG;IACH,SAAS,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC;IAI1B;;OAEG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAkC1B;;;OAGG;cACa,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5D,+DAA+D;IAC/D,SAAS,CAAC,QAAQ,CAAC,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC;CACnD"}
+{"version":3,"file":"base-cli-plugin.d.ts","sourceRoot":"","sources":["../src/base-cli-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAS,MAAM,aAAa,CAAC;AAI7C,OAAO,EAAmB,KAAK,iBAAiB,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtG;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8BAAsB,aAAc,SAAQ,OAAO;IACjD,gFAAgF;IAChF,OAAgB,SAAS;;;;;MAevB;IAEF;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC;IAE1B,SAAS,CAAC,IAAI,EAAG,iBAAiB,CAAC;IAEnC;;;;;OAKG;IACH,SAAS,CAAC,WAAW,UAAS;IAE9B,6EAA6E;IAC7E,OAAO,CAAC,WAAW,CAAU;IAE7B;;;;;;;;;OASG;IACH,SAAS,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC;IAI1B;;OAEG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAoC1B;;;;;;OAMG;YACW,UAAU;IAcxB;;;OAGG;cACa,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5D,+DAA+D;IAC/D,SAAS,CAAC,QAAQ,CAAC,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC;CACnD"}

package/dist/base-cli-plugin.js

@@ -1,5 +1,8 @@
 import { Command, Flags } from '@oclif/core';
 import { MJCLIRuntimeHost } from './runtime-host.js';
+import { ResolveOutputFormat } from './output-format.js';
+import { NonInteractiveError, ResolveInteractivity } from './interaction.js';
+import { MJCLIErrorCodes } from './types.js';
 /**
  * Abstract base for every pluggable `mj` command (plan D1/D2).
  *
@@ -9,20 +12,45 @@ import { MJCLIRuntimeHost } from './runtime-host.js';
  * shared {@link BaseCLIPlugin.run} wires up the {@link IMJCLIRuntimeHost}, emits
  * the runtime advisory, renders the result per `--format`, and sets the exit code.
  *
- * The global flags `--format`, `--verbose`, and `--no-banner` are declared on
- * {@link BaseCLIPlugin.baseFlags} and inherited by every subclass via oclif's
- * native `baseFlags` merging — no per-command duplication (plan D3).
+ * The global flags `--format`, `--verbose`, `--no-banner`, and `--interactive`
+ * are declared on {@link BaseCLIPlugin.baseFlags} and inherited by every subclass
+ * via oclif's native `baseFlags` merging — no per-command duplication (plan D3).
+ *
+ * Two defaults are inferred here rather than declared per command, so that a human
+ * and an agent each get the right behaviour without either having to ask for it:
+ * - **Format follows the pipe.** With no explicit `--format`, a non-TTY stdout
+ *   resolves to `json`. A caller that redirected stdout has already said it is a
+ *   machine; it should not also have to remember a flag.
+ * - **Prompting follows the terminal.** {@link BaseCLIPlugin.Interactive} is true at a
+ *   real terminal and false when piped, spawned, or running in CI. A
+ *   {@link NonInteractiveError} escaping `Execute` is rendered as a structured,
+ *   actionable result rather than a stack trace.
  */
 export class BaseCLIPlugin extends Command {
+    constructor() {
+        super(...arguments);
+        /**
+         * Whether this run may prompt — detected from the terminal unless `--interactive` /
+         * `--no-interactive` says otherwise. Subclasses pass this into `ResolveOrPrompt`
+         * rather than calling `@inquirer` directly, so a missing value fails fast with the
+         * flag to pass instead of blocking on stdin.
+         */
+        this.Interactive = false;
+    }
     /** Inherited by every subclass through oclif's static `baseFlags` mechanism. */
     static { this.baseFlags = {
         format: Flags.string({
-            options: ['text', 'json', 'md'],
-            default: 'text',
-            description: 'Output format: text (human), json (machine-readable), md (Markdown-fenced)',
+            options: ['text', 'json', 'md', 'human', 'console', 'markdown'],
+            description: 'Output format: text (human), json (machine-readable), md (Markdown-fenced). ' +
+                'Defaults to text on a terminal and json when stdout is piped.',
         }),
         verbose: Flags.boolean({ char: 'v', default: false, description: 'Show detailed output' }),
         'no-banner': Flags.boolean({ default: false, description: 'Suppress the startup banner and runtime advisory' }),
+        interactive: Flags.boolean({
+            allowNo: true,
+            description: 'Allow interactive prompts. Defaults to on at a terminal and off when piped, spawned, or in CI, ' +
+                'so an agent never hangs on a question. Use --no-interactive to force it off.',
+        }),
     }; }
     /**
      * The flags parsed for this command. Subclasses call this in {@link Execute}
@@ -47,16 +75,17 @@ export class BaseCLIPlugin extends Command {
         const { flags } = await this.parse(ctor);
         this.parsedFlags = flags;
         const f = flags;
-        const format = f.format ?? 'text';
+        const { format } = ResolveOutputFormat({ formatFlag: f.format });
         const verbose = !!f.verbose;
         const noBanner = !!f['no-banner'];
-        this.Host = new MJCLIRuntimeHost(format, verbose, noBanner);
+        this.Interactive = ResolveInteractivity({ interactiveFlag: f.interactive }).interactive;
+        this.Host = new MJCLIRuntimeHost(format, verbose, noBanner, { interactive: this.Interactive });
         // Announce runtime expectation up front (stderr in JSON mode) so an agent
         // reading the stream can budget its timeout — see plan §5/§6.
         if (ctor.Usage) {
             this.Host.AnnounceRuntime(ctor.Usage);
         }
-        const result = await this.Execute();
+        const result = await this.RunExecute(ctor);
         this.Host.Emit(result);
         // Optional cleanup hook (e.g. close DB pools, reset singletons). Runs after
         // Emit so the result is always rendered even when cleanup hard-exits.
@@ -67,6 +96,28 @@ export class BaseCLIPlugin extends Command {
             this.exit(1);
         }
     }
+    /**
+     * Runs {@link BaseCLIPlugin.Execute}, converting a {@link NonInteractiveError} into a
+     * normal failed result. A command that asked for a value it wasn't given has NOT
+     * crashed — it has a precise, recoverable complaint, and an agent gets far more from
+     * `{code:'E_NON_INTERACTIVE', suggestion:'Pass --entity …'}` than from a stack trace.
+     * Every other error keeps propagating to oclif untouched.
+     */
+    async RunExecute(ctor) {
+        try {
+            return await this.Execute();
+        }
+        catch (e) {
+            if (!(e instanceof NonInteractiveError))
+                throw e;
+            return {
+                success: false,
+                command: ctor.Usage?.command ?? this.id ?? 'unknown',
+                durationSeconds: 0,
+                errors: [{ message: e.message, code: MJCLIErrorCodes.NonInteractive, suggestion: e.suggestion }],
+            };
+        }
+    }
     /**
      * Optional post-Emit hook. Override to release resources (DB pools, singletons)
      * and, when necessary, `process.exit()` to terminate lingering background work.

package/dist/base-cli-plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"base-cli-plugin.js","sourceRoot":"","sources":["../src/base-cli-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGlD;;;;;;;;;;;;GAYG;AACH,MAAM,OAAgB,aAAc,SAAQ,OAAO;IACjD,gFAAgF;aAChE,cAAS,GAAG;QAC1B,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC;YACnB,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC;YAC/B,OAAO,EAAE,MAAM;YACf,WAAW,EAAE,4EAA4E;SAC1F,CAAC;QACF,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,sBAAsB,EAAE,CAAC;QAC1F,WAAW,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,kDAAkD,EAAE,CAAC;KAChH,CAAC;IAeF;;;;;;;;;OASG;IACO,QAAQ;QAChB,OAAO,IAAI,CAAC,WAA2B,CAAC;IAC1C,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG;QACP,4EAA4E;QAC5E,6EAA6E;QAC7E,MAAM,IAAI,GAAG,IAAI,CAAC,WAAmC,CAAC;QACtD,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;QAEzB,MAAM,CAAC,GAAG,KAAsE,CAAC;QACjF,MAAM,MAAM,GAAI,CAAC,CAAC,MAAuB,IAAI,MAAM,CAAC;QACpD,MAAM,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;QAC5B,MAAM,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;QAElC,IAAI,CAAC,IAAI,GAAG,IAAI,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;QAE5D,0EAA0E;QAC1E,8DAA8D;QAC9D,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxC,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACpC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAEvB,4EAA4E;QAC5E,sEAAsE;QACtE,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAE3B,wEAAwE;QACxE,2DAA2D;QAC3D,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;OAGG;IACO,KAAK,CAAC,OAAO,CAAC,OAAoB;QAC1C,mBAAmB;IACrB,CAAC"}
+{"version":3,"file":"base-cli-plugin.js","sourceRoot":"","sources":["../src/base-cli-plugin.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,7 +1,13 @@
 export * from './types.js';
 export { MJCLIRuntimeHost } from './runtime-host.js';
+export type { RuntimeHostOptions } from './runtime-host.js';
 export { BaseCLIPlugin } from './base-cli-plugin.js';
 export { SerializeResult } from './serialize.js';
+export type { SerializeOptions } from './serialize.js';
+export { ResolveOutputFormat, NormalizeFormatAlias, ShouldSuppressChrome, FORMAT_ENV, } from './output-format.js';
+export type { FormatResolutionInput, FormatResolution } from './output-format.js';
+export { ResolveInteractivity, ResolveOrPrompt, RequireInteractive, NonInteractiveError, INTERACTIVE_ENV, NON_INTERACTIVE_CODE, } from './interaction.js';
+export type { InteractivityInput, InteractivityDecision, InteractivityReason, ResolveOrPromptOptions, } from './interaction.js';
 export { CLIPluginRegistry, PLUGIN_CONFIG_FILENAME, } from './plugin-registry.js';
 export type { UsageDomainSummary, UsageDomainMap, UsageDomainDetail, PluginLoadResult, } from './plugin-registry.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,UAAU,GACX,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,GACrB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -2,5 +2,7 @@ export * from './types.js';
 export { MJCLIRuntimeHost } from './runtime-host.js';
 export { BaseCLIPlugin } from './base-cli-plugin.js';
 export { SerializeResult } from './serialize.js';
+export { ResolveOutputFormat, NormalizeFormatAlias, ShouldSuppressChrome, FORMAT_ENV, } from './output-format.js';
+export { ResolveInteractivity, ResolveOrPrompt, RequireInteractive, NonInteractiveError, INTERACTIVE_ENV, NON_INTERACTIVE_CODE, } from './interaction.js';
 export { CLIPluginRegistry, PLUGIN_CONFIG_FILENAME, } from './plugin-registry.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,UAAU,GACX,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAOvB,OAAO,EACL,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC"}

package/dist/interaction.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Forces interactivity on (`1`/`true`) or off (`0`/`false`) for a whole shell session,
+ * overriding TTY detection. An agent harness that shells out through a pty should set
+ * this to `0` so its subprocesses can never block on a question.
+ */
+export declare const INTERACTIVE_ENV = "MJ_CLI_INTERACTIVE";
+/**
+ * Stable code carried by {@link NonInteractiveError} and its result-envelope entry.
+ * Re-exported from the {@link MJCLIErrorCodes} catalog rather than restated, so the
+ * error thrown here and the `code` an agent branches on can never drift apart.
+ */
+export declare const NON_INTERACTIVE_CODE: "E_NON_INTERACTIVE";
+/** Inputs to {@link ResolveInteractivity}. Every field is injectable for tests. */
+export interface InteractivityInput {
+    /**
+     * The `--interactive` / `--no-interactive` flag value, when the caller passed one.
+     * `undefined` means "not specified" — that is what lets detection run.
+     */
+    interactiveFlag?: boolean;
+    /** Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Defaults to `process.stdin.isTTY`. A prompt needs a real stdin to read from. */
+    stdinIsTTY?: boolean;
+    /** Defaults to `process.stdout.isTTY`. A prompt needs a real stdout to render on. */
+    stdoutIsTTY?: boolean;
+}
+/** Why this run may or may not prompt. Machine-stable, so errors and tests can use it. */
+export type InteractivityReason = 
+/** `--no-interactive` was passed. */
+'flag-off'
+/** `--interactive` was passed and there is a usable terminal. */
+ | 'flag-on'
+/** {@link INTERACTIVE_ENV} is `0`/`false`. */
+ | 'env-off'
+/** {@link INTERACTIVE_ENV} is `1`/`true` and there is a usable terminal. */
+ | 'env-on'
+/** No terminal on stdin and/or stdout — piped, redirected, or spawned. */
+ | 'no-tty'
+/** A terminal is present, but a CI environment variable says this is a build. */
+ | 'ci'
+/** `TERM=dumb` — a terminal that cannot render a prompt. */
+ | 'dumb-terminal'
+/** A real terminal with nothing indicating otherwise: a human is presumed present. */
+ | 'tty-detected';
+/** The decision plus the rule that produced it. */
+export interface InteractivityDecision {
+    interactive: boolean;
+    reason: InteractivityReason;
+}
+/**
+ * Decides whether this run may prompt, most explicit signal first:
+ *
+ * 1. `--no-interactive` → never
+ * 2. `--interactive` → yes, if there is a terminal to prompt on
+ * 3. {@link INTERACTIVE_ENV} → the same, one level down
+ * 4. no terminal on stdin or stdout → never
+ * 5. a CI environment variable is set → never
+ * 6. `TERM=dumb` → never
+ * 7. otherwise → yes; a real terminal means a human
+ *
+ * Note the asymmetry at steps 2 and 3: asking for interactivity without a terminal
+ * resolves to NON-interactive with reason `no-tty` rather than throwing. The caller
+ * is then free to fail at the exact point a value is missing, which is far more
+ * actionable than a blanket "no TTY" error at startup.
+ */
+export declare function ResolveInteractivity(input?: InteractivityInput): InteractivityDecision;
+/**
+ * Thrown when a command needs a value it wasn't given and isn't allowed to ask for.
+ *
+ * Carries the two fields an agent needs to recover unaided: a stable
+ * {@link NonInteractiveError.code} to branch on, and a {@link NonInteractiveError.suggestion}
+ * naming the exact flag to pass. `MJCLIResultError` mirrors both, so a plugin can put
+ * this straight into its result envelope.
+ */
+export declare class NonInteractiveError extends Error {
+    /** Always {@link NON_INTERACTIVE_CODE}. */
+    readonly code: "E_NON_INTERACTIVE";
+    /** The concrete remedy, e.g. `Pass --entity "MJ: AI Prompts".` */
+    readonly suggestion: string;
+    /** Why prompting was refused — from {@link InteractivityDecision.reason}. */
+    readonly reason: InteractivityReason;
+    constructor(what: string, suggestion: string, reason: InteractivityReason);
+}
+/** Options for {@link ResolveOrPrompt}. */
+export interface ResolveOrPromptOptions<T> {
+    /**
+     * The value already supplied by a flag. Any value other than `undefined` wins
+     * outright — including `false` and `''`, which are legitimate answers.
+     */
+    flagValue: T | undefined;
+    /** Asks the human. Only ever invoked when {@link ResolveInteractivity} allows it. */
+    prompt: () => Promise<T>;
+    /** What is being asked for, for the error message — e.g. `An entity name`. */
+    what: string;
+    /** The exact remedy, e.g. `Pass --entity "MJ: AI Prompts".` */
+    suggestion: string;
+    /** Interactivity state; defaults to reading the env/TTY. */
+    interactivity?: InteractivityInput;
+}
+/**
+ * The single choke point every prompt in the CLI goes through.
+ *
+ * Resolution order: an explicit flag wins; otherwise prompt if this run is allowed to;
+ * otherwise throw {@link NonInteractiveError} naming the flag. A command that routes all
+ * its prompts through this can never hang an agent, and still behaves exactly as before
+ * for a human at a terminal.
+ */
+export declare function ResolveOrPrompt<T>(options: ResolveOrPromptOptions<T>): Promise<T>;
+/**
+ * Guards a whole command (rather than one value) that is interactive by nature — e.g.
+ * the setup wizard, which asks two dozen questions with no flag equivalents. Throws
+ * {@link NonInteractiveError} unless this run may prompt.
+ */
+export declare function RequireInteractive(what: string, suggestion: string, interactivity?: InteractivityInput): void;
+//# sourceMappingURL=interaction.d.ts.map

package/dist/interaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction.d.ts","sourceRoot":"","sources":["../src/interaction.ts"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,eAAO,MAAM,eAAe,uBAAuB,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,qBAAiC,CAAC;AAoBnE,mFAAmF;AACnF,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,mFAAmF;IACnF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,qFAAqF;IACrF,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,0FAA0F;AAC1F,MAAM,MAAM,mBAAmB;AAC7B,qCAAqC;AACnC,UAAU;AACZ,iEAAiE;GAC/D,SAAS;AACX,8CAA8C;GAC5C,SAAS;AACX,4EAA4E;GAC1E,QAAQ;AACV,0EAA0E;GACxE,QAAQ;AACV,iFAAiF;GAC/E,IAAI;AACN,4DAA4D;GAC1D,eAAe;AACjB,sFAAsF;GACpF,cAAc,CAAC;AAEnB,mDAAmD;AACnD,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAkBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,GAAE,kBAAuB,GAAG,qBAAqB,CAsB1F;AAmCD;;;;;;;GAOG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,2CAA2C;IAC3C,SAAgB,IAAI,sBAAwB;IAC5C,kEAAkE;IAClE,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,6EAA6E;IAC7E,SAAgB,MAAM,EAAE,mBAAmB,CAAC;gBAEhC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB;CAM1E;AAED,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC;;;OAGG;IACH,SAAS,EAAE,CAAC,GAAG,SAAS,CAAC;IACzB,qFAAqF;IACrF,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;IACzB,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,aAAa,CAAC,EAAE,kBAAkB,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAOvF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAG7G"}

package/dist/interaction.js

@@ -0,0 +1,182 @@
+/**
+ * Interactivity resolution: detect whether a human is actually present, and let
+ * either side say otherwise explicitly.
+ *
+ * A prompt is a blocking question. A human at a terminal can answer one; an agent,
+ * a CI job, or a container cannot, and under the old behaviour it simply hung on
+ * stdin with no output explaining why. The fix is not to take prompting away from
+ * humans — it is to stop *assuming* one is there.
+ *
+ * So the default is inferred rather than fixed: a real terminal on both stdin and
+ * stdout means a human, and everything else means automation. `--interactive` and
+ * `--no-interactive` (plus {@link INTERACTIVE_ENV}) override the inference in either
+ * direction. When a command needs a value it wasn't given and may not ask for it, it
+ * **fails fast naming the flag** instead of waiting on stdin.
+ *
+ * Both entry points here are pure functions over injected state — no direct
+ * `process` reads — so a test can drive every branch without a real TTY.
+ */
+import { MJCLIErrorCodes } from './types.js';
+/**
+ * Forces interactivity on (`1`/`true`) or off (`0`/`false`) for a whole shell session,
+ * overriding TTY detection. An agent harness that shells out through a pty should set
+ * this to `0` so its subprocesses can never block on a question.
+ */
+export const INTERACTIVE_ENV = 'MJ_CLI_INTERACTIVE';
+/**
+ * Stable code carried by {@link NonInteractiveError} and its result-envelope entry.
+ * Re-exported from the {@link MJCLIErrorCodes} catalog rather than restated, so the
+ * error thrown here and the `code` an agent branches on can never drift apart.
+ */
+export const NON_INTERACTIVE_CODE = MJCLIErrorCodes.NonInteractive;
+/**
+ * Environment variables that mean "this is an automated build", checked when a TTY is
+ * present anyway (some runners allocate one). Any value other than the empty string,
+ * `0`, or `false` counts as set — CI systems variously use `true`, `1`, or their own name.
+ */
+const CI_ENV_VARS = [
+    'CI',
+    'CONTINUOUS_INTEGRATION',
+    'GITHUB_ACTIONS',
+    'GITLAB_CI',
+    'BUILDKITE',
+    'CIRCLECI',
+    'TRAVIS',
+    'TEAMCITY_VERSION',
+    'TF_BUILD',
+    'JENKINS_URL',
+];
+/** Treats `''`, `'0'`, and `'false'` as unset; anything else as set. */
+function envFlagIsSet(value) {
+    if (value === undefined)
+        return false;
+    const v = value.trim().toLowerCase();
+    return v !== '' && v !== '0' && v !== 'false';
+}
+/** `1`/`true` → true, `0`/`false` → false, anything else (including unset) → undefined. */
+function envTriState(value) {
+    if (value === undefined)
+        return undefined;
+    const v = value.trim().toLowerCase();
+    if (v === '1' || v === 'true')
+        return true;
+    if (v === '0' || v === 'false')
+        return false;
+    return undefined;
+}
+/**
+ * Decides whether this run may prompt, most explicit signal first:
+ *
+ * 1. `--no-interactive` → never
+ * 2. `--interactive` → yes, if there is a terminal to prompt on
+ * 3. {@link INTERACTIVE_ENV} → the same, one level down
+ * 4. no terminal on stdin or stdout → never
+ * 5. a CI environment variable is set → never
+ * 6. `TERM=dumb` → never
+ * 7. otherwise → yes; a real terminal means a human
+ *
+ * Note the asymmetry at steps 2 and 3: asking for interactivity without a terminal
+ * resolves to NON-interactive with reason `no-tty` rather than throwing. The caller
+ * is then free to fail at the exact point a value is missing, which is far more
+ * actionable than a blanket "no TTY" error at startup.
+ */
+export function ResolveInteractivity(input = {}) {
+    const env = input.env ?? process.env;
+    const stdinIsTTY = input.stdinIsTTY ?? process.stdin.isTTY === true;
+    const stdoutIsTTY = input.stdoutIsTTY ?? process.stdout.isTTY === true;
+    const hasTerminal = stdinIsTTY && stdoutIsTTY;
+    if (input.interactiveFlag === false)
+        return { interactive: false, reason: 'flag-off' };
+    if (input.interactiveFlag === true) {
+        return hasTerminal ? { interactive: true, reason: 'flag-on' } : { interactive: false, reason: 'no-tty' };
+    }
+    const fromEnv = envTriState(env[INTERACTIVE_ENV]);
+    if (fromEnv === false)
+        return { interactive: false, reason: 'env-off' };
+    if (fromEnv === true) {
+        return hasTerminal ? { interactive: true, reason: 'env-on' } : { interactive: false, reason: 'no-tty' };
+    }
+    if (!hasTerminal)
+        return { interactive: false, reason: 'no-tty' };
+    if (CI_ENV_VARS.some((name) => envFlagIsSet(env[name])))
+        return { interactive: false, reason: 'ci' };
+    if (env.TERM?.trim().toLowerCase() === 'dumb')
+        return { interactive: false, reason: 'dumb-terminal' };
+    return { interactive: true, reason: 'tty-detected' };
+}
+/** Explains, in one clause, why prompting was refused — so the error can say it out loud. */
+function describeReason(reason) {
+    switch (reason) {
+        case 'no-tty':
+            return 'this run has no interactive terminal';
+        case 'ci':
+            return 'this run looks like CI';
+        case 'dumb-terminal':
+            return 'this terminal cannot display a prompt (TERM=dumb)';
+        case 'flag-off':
+            return '--no-interactive was passed';
+        case 'env-off':
+            return `${INTERACTIVE_ENV} is set to off`;
+        default:
+            return 'this run is non-interactive';
+    }
+}
+/** The "you could also just ask me" half of the message, omitted when it would be wrong. */
+function describeRemedy(reason) {
+    // Telling someone to pass --interactive when there is no terminal to prompt on
+    // would send them in a circle.
+    switch (reason) {
+        case 'no-tty':
+        case 'dumb-terminal':
+            return '';
+        case 'flag-off':
+            return ' (Or drop --no-interactive to be prompted for it.)';
+        default:
+            return ' (Or pass --interactive to be prompted for it.)';
+    }
+}
+/**
+ * Thrown when a command needs a value it wasn't given and isn't allowed to ask for.
+ *
+ * Carries the two fields an agent needs to recover unaided: a stable
+ * {@link NonInteractiveError.code} to branch on, and a {@link NonInteractiveError.suggestion}
+ * naming the exact flag to pass. `MJCLIResultError` mirrors both, so a plugin can put
+ * this straight into its result envelope.
+ */
+export class NonInteractiveError extends Error {
+    constructor(what, suggestion, reason) {
+        super(`${what} is required and ${describeReason(reason)}. ${suggestion}${describeRemedy(reason)}`);
+        /** Always {@link NON_INTERACTIVE_CODE}. */
+        this.code = NON_INTERACTIVE_CODE;
+        this.name = 'NonInteractiveError';
+        this.suggestion = suggestion;
+        this.reason = reason;
+    }
+}
+/**
+ * The single choke point every prompt in the CLI goes through.
+ *
+ * Resolution order: an explicit flag wins; otherwise prompt if this run is allowed to;
+ * otherwise throw {@link NonInteractiveError} naming the flag. A command that routes all
+ * its prompts through this can never hang an agent, and still behaves exactly as before
+ * for a human at a terminal.
+ */
+export async function ResolveOrPrompt(options) {
+    if (options.flagValue !== undefined)
+        return options.flagValue;
+    const decision = ResolveInteractivity(options.interactivity);
+    if (decision.interactive)
+        return await options.prompt();
+    throw new NonInteractiveError(options.what, options.suggestion, decision.reason);
+}
+/**
+ * Guards a whole command (rather than one value) that is interactive by nature — e.g.
+ * the setup wizard, which asks two dozen questions with no flag equivalents. Throws
+ * {@link NonInteractiveError} unless this run may prompt.
+ */
+export function RequireInteractive(what, suggestion, interactivity) {
+    const decision = ResolveInteractivity(interactivity);
+    if (!decision.interactive)
+        throw new NonInteractiveError(what, suggestion, decision.reason);
+}
+//# sourceMappingURL=interaction.js.map

package/dist/interaction.js.map

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

package/dist/output-format.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Dual-output resolution: a human at a terminal gets text, a pipe gets JSON.
+ *
+ * The agent-facing failure this fixes is mundane and constant — `mj codegen | jq`
+ * used to hand `jq` a figlet banner and a spinner, because the machine format was
+ * only reachable by remembering `--format=json`. A caller that redirects stdout has
+ * already told us it is a machine; nothing further should be required of it.
+ *
+ * {@link ResolveOutputFormat} is a pure function over injected state so every
+ * precedence rule is testable without a real TTY.
+ */
+import type { OutputFormat } from './types.js';
+/** Env var that pins the output format for a whole shell session. */
+export declare const FORMAT_ENV = "MJ_CLI_FORMAT";
+/** Inputs to {@link ResolveOutputFormat}. Every field is injectable for tests. */
+export interface FormatResolutionInput {
+    /** Raw `--format` value, if the caller passed one. Accepts the aliases below. */
+    formatFlag?: string;
+    /** Legacy `--json` boolean, still declared by a few commands. */
+    jsonFlag?: boolean;
+    /** Defaults to `process.stdout.isTTY`. */
+    stdoutIsTTY?: boolean;
+    /** Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+/** The resolved format plus the rule that produced it (machine-stable, for tests and `--verbose`). */
+export interface FormatResolution {
+    format: OutputFormat;
+    reason: 'format-flag' | 'json-flag' | 'env' | 'piped' | 'tty-default';
+}
+/**
+ * Canonicalizes the spellings different MJ command families grew independently.
+ *
+ * `mj test *` shipped `console|json|markdown`, `mj ai *` shipped `compact|json|table`,
+ * and the plugin commands shipped `text|json|md`. All three keep working; they just
+ * mean the same three things now. Returns `undefined` for an unrecognized value so
+ * the caller can fall through rather than silently picking a format.
+ */
+export declare function NormalizeFormatAlias(value: string | undefined): OutputFormat | undefined;
+/**
+ * Resolves the output format, most explicit signal first:
+ *
+ * 1. `--format` (any recognized alias)
+ * 2. `--json`
+ * 3. {@link FORMAT_ENV}
+ * 4. stdout is not a TTY → `json` — the pipe *is* the request
+ * 5. otherwise `text`
+ */
+export declare function ResolveOutputFormat(input?: FormatResolutionInput): FormatResolution;
+/**
+ * True when decorative chrome (banner, spinners, color) should be suppressed:
+ * any machine format, or a non-TTY stdout even in text mode.
+ *
+ * Kept separate from format resolution because a command can legitimately be in
+ * text mode while piped (`--format=text > file.txt`) and still want no spinner.
+ */
+export declare function ShouldSuppressChrome(format: OutputFormat, stdoutIsTTY?: boolean): boolean;
+//# sourceMappingURL=output-format.d.ts.map

package/dist/output-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-format.d.ts","sourceRoot":"","sources":["../src/output-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,qEAAqE;AACrE,eAAO,MAAM,UAAU,kBAAkB,CAAC;AAE1C,kFAAkF;AAClF,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0CAA0C;IAC1C,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,sGAAsG;AACtG,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,aAAa,GAAG,WAAW,GAAG,KAAK,GAAG,OAAO,GAAG,aAAa,CAAC;CACvE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAkBxF;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,GAAE,qBAA0B,GAAG,gBAAgB,CAevF;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,OAAO,CAGzF"}

package/dist/output-format.js

@@ -0,0 +1,67 @@
+/** Env var that pins the output format for a whole shell session. */
+export const FORMAT_ENV = 'MJ_CLI_FORMAT';
+/**
+ * Canonicalizes the spellings different MJ command families grew independently.
+ *
+ * `mj test *` shipped `console|json|markdown`, `mj ai *` shipped `compact|json|table`,
+ * and the plugin commands shipped `text|json|md`. All three keep working; they just
+ * mean the same three things now. Returns `undefined` for an unrecognized value so
+ * the caller can fall through rather than silently picking a format.
+ */
+export function NormalizeFormatAlias(value) {
+    if (!value)
+        return undefined;
+    switch (value.trim().toLowerCase()) {
+        case 'text':
+        case 'human':
+        case 'pretty':
+        case 'console':
+        case 'compact':
+        case 'table':
+            return 'text';
+        case 'json':
+            return 'json';
+        case 'md':
+        case 'markdown':
+            return 'md';
+        default:
+            return undefined;
+    }
+}
+/**
+ * Resolves the output format, most explicit signal first:
+ *
+ * 1. `--format` (any recognized alias)
+ * 2. `--json`
+ * 3. {@link FORMAT_ENV}
+ * 4. stdout is not a TTY → `json` — the pipe *is* the request
+ * 5. otherwise `text`
+ */
+export function ResolveOutputFormat(input = {}) {
+    const env = input.env ?? process.env;
+    const explicit = NormalizeFormatAlias(input.formatFlag);
+    if (explicit)
+        return { format: explicit, reason: 'format-flag' };
+    if (input.jsonFlag === true)
+        return { format: 'json', reason: 'json-flag' };
+    const fromEnv = NormalizeFormatAlias(env[FORMAT_ENV]);
+    if (fromEnv)
+        return { format: fromEnv, reason: 'env' };
+    const stdoutIsTTY = input.stdoutIsTTY ?? process.stdout.isTTY === true;
+    if (!stdoutIsTTY)
+        return { format: 'json', reason: 'piped' };
+    return { format: 'text', reason: 'tty-default' };
+}
+/**
+ * True when decorative chrome (banner, spinners, color) should be suppressed:
+ * any machine format, or a non-TTY stdout even in text mode.
+ *
+ * Kept separate from format resolution because a command can legitimately be in
+ * text mode while piped (`--format=text > file.txt`) and still want no spinner.
+ */
+export function ShouldSuppressChrome(format, stdoutIsTTY) {
+    if (format !== 'text')
+        return true;
+    return !(stdoutIsTTY ?? process.stdout.isTTY === true);
+}
+//# sourceMappingURL=output-format.js.map

package/dist/output-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-format.js","sourceRoot":"","sources":["../src/output-format.ts"],"names":[],"mappings":"AAaA,qEAAqE;AACrE,MAAM,CAAC,MAAM,UAAU,GAAG,eAAe,CAAC;AAoB1C;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAyB;IAC5D,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC;QACnC,KAAK,MAAM,CAAC;QACZ,KAAK,OAAO,CAAC;QACb,KAAK,QAAQ,CAAC;QACd,KAAK,SAAS,CAAC;QACf,KAAK,SAAS,CAAC;QACf,KAAK,OAAO;YACV,OAAO,MAAM,CAAC;QAChB,KAAK,MAAM;YACT,OAAO,MAAM,CAAC;QAChB,KAAK,IAAI,CAAC;QACV,KAAK,UAAU;YACb,OAAO,IAAI,CAAC;QACd;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAA+B,EAAE;IACnE,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IAErC,MAAM,QAAQ,GAAG,oBAAoB,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IACxD,IAAI,QAAQ;QAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;IAEjE,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI;QAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAE5E,MAAM,OAAO,GAAG,oBAAoB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC;IACtD,IAAI,OAAO;QAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAEvD,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI,CAAC;IACvE,IAAI,CAAC,WAAW;QAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAE7D,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAoB,EAAE,WAAqB;IAC9E,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,CAAC,CAAC,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC;AACzD,CAAC"}

package/dist/plugin-registry.d.ts

@@ -67,6 +67,25 @@ export declare class CLIPluginRegistry {
      * Registering the same `command` twice keeps the first declaration, matching the
      * de-duplication rule {@link CLIPluginRegistry.GetAllUsage} applies to plugins.
      */
+    /**
+     * Human-authored one-line summaries for the tier-1 domain map, keyed by domain.
+     * See {@link CLIPluginRegistry.RegisterDomainSummary}.
+     */
+    private static readonly domainSummaries;
+    /**
+     * Declares the tier-1 summary for a whole domain, overriding the line
+     * {@link CLIPluginRegistry.domainSummary} would otherwise synthesize from its
+     * commands.
+     *
+     * Worth having because the synthesized line degrades badly once a domain has more
+     * than a couple of commands — `mj test`'s 16 commands would render as one command's
+     * summary plus "(+15 more commands)", which tells an agent nothing about what the
+     * domain is FOR. A domain with no registered summary keeps the synthesized line, so
+     * this is an opt-in improvement rather than a new requirement.
+     *
+     * First registration wins, matching {@link CLIPluginRegistry.RegisterUsage}.
+     */
+    static RegisterDomainSummary(domain: string, summary: string): void;
     static RegisterUsage(usage: PluginUsage): void;
     /**
      * Every command's usage metadata, de-duplicated by command key: the registered

package/dist/plugin-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-registry.d.ts","sourceRoot":"","sources":["../src/plugin-registry.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAErE,sEAAsE;AACtE,eAAO,MAAM,sBAAsB,wBAAwB,CAAC;AAM5D,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,iFAAiF;IACjF,MAAM,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAED,+BAA+B;AAC/B,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;CAC/B;AAED,6BAA6B;AAC7B,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,kBAAkB,EAAE,CAAC;CAC/B;AAED,qDAAqD;AACrD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAID;;;;;GAKG;AACH,qBAAa,iBAAiB;IAC5B;;;;;OAKG;WACU,qBAAqB,CAAC,QAAQ,GAAE,MAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA+B/F;;;;OAIG;mBACkB,eAAe;IASpC,0EAA0E;IAC1E,OAAO,CAAC,MAAM,CAAC,UAAU;IAYzB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAkC;IAEzE;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAQ9C;;;;OAIG;IACH,MAAM,CAAC,WAAW,IAAI,WAAW,EAAE;IAenC,+EAA+E;IAC/E,MAAM,CAAC,cAAc,IAAI,cAAc;IAoBvC,sFAAsF;IACtF,MAAM,CAAC,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB;IAQ3D,uEAAuE;IACvE,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW;IAI5E;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAU5B;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;CAQlC"}
+{"version":3,"file":"plugin-registry.d.ts","sourceRoot":"","sources":["../src/plugin-registry.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAErE,sEAAsE;AACtE,eAAO,MAAM,sBAAsB,wBAAwB,CAAC;AAM5D,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,iFAAiF;IACjF,MAAM,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAED,+BAA+B;AAC/B,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;CAC/B;AAED,6BAA6B;AAC7B,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,kBAAkB,EAAE,CAAC;CAC/B;AAED,qDAAqD;AACrD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAID;;;;;GAKG;AACH,qBAAa,iBAAiB;IAC5B;;;;;OAKG;WACU,qBAAqB,CAAC,QAAQ,GAAE,MAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA+B/F;;;;OAIG;mBACkB,eAAe;IASpC,0EAA0E;IAC1E,OAAO,CAAC,MAAM,CAAC,UAAU;IAYzB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAkC;IAEzE;;;;;;;;;;;OAWG;IACH;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAA6B;IAEpE;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAMnE,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAQ9C;;;;OAIG;IACH,MAAM,CAAC,WAAW,IAAI,WAAW,EAAE;IAenC,+EAA+E;IAC/E,MAAM,CAAC,cAAc,IAAI,cAAc;IAoBvC,sFAAsF;IACtF,MAAM,CAAC,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB;IAQ3D,uEAAuE;IACvE,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW;IAI5E;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAY5B;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;CAQlC"}

package/dist/plugin-registry.js

@@ -94,6 +94,31 @@ export class CLIPluginRegistry {
      * Registering the same `command` twice keeps the first declaration, matching the
      * de-duplication rule {@link CLIPluginRegistry.GetAllUsage} applies to plugins.
      */
+    /**
+     * Human-authored one-line summaries for the tier-1 domain map, keyed by domain.
+     * See {@link CLIPluginRegistry.RegisterDomainSummary}.
+     */
+    static { this.domainSummaries = new Map(); }
+    /**
+     * Declares the tier-1 summary for a whole domain, overriding the line
+     * {@link CLIPluginRegistry.domainSummary} would otherwise synthesize from its
+     * commands.
+     *
+     * Worth having because the synthesized line degrades badly once a domain has more
+     * than a couple of commands — `mj test`'s 16 commands would render as one command's
+     * summary plus "(+15 more commands)", which tells an agent nothing about what the
+     * domain is FOR. A domain with no registered summary keeps the synthesized line, so
+     * this is an opt-in improvement rather than a new requirement.
+     *
+     * First registration wins, matching {@link CLIPluginRegistry.RegisterUsage}.
+     */
+    static RegisterDomainSummary(domain, summary) {
+        const key = domain.trim().toLowerCase();
+        if (!key || !summary)
+            return;
+        if (!this.domainSummaries.has(key))
+            this.domainSummaries.set(key, summary);
+    }
     static RegisterUsage(usage) {
         if (!usage?.domain || !usage?.command) {
             throw new Error('RegisterUsage requires a usage object with both domain and command set');
@@ -157,6 +182,9 @@ export class CLIPluginRegistry {
      * use it; otherwise join the command summaries compactly.
      */
     static domainSummary(domain, cmds) {
+        const declared = this.domainSummaries.get(domain.trim().toLowerCase());
+        if (declared)
+            return declared;
         if (cmds.length === 1)
             return cmds[0].summary;
         // Prefer a command whose key equals the domain (e.g. 'codegen').

package/dist/plugin-registry.js.map

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

package/dist/runtime-host.d.ts

@@ -1,4 +1,11 @@
 import type { IMJCLIRuntimeHost, LogLevel, MJCLIResult, OutputFormat, PluginUsage } from './types.js';
+/** Construction-time state for {@link MJCLIRuntimeHost}. Injectable so tests need no real TTY. */
+export interface RuntimeHostOptions {
+    /** Whether this run may prompt — from `ResolveInteractivity`. Defaults to false (agent-first). */
+    interactive?: boolean;
+    /** Defaults to `process.stdout.isTTY`. */
+    stdoutIsTTY?: boolean;
+}
 /**
  * Default implementation of {@link IMJCLIRuntimeHost}.
  *
@@ -13,20 +20,31 @@ import type { IMJCLIRuntimeHost, LogLevel, MJCLIResult, OutputFormat, PluginUsag
  *   pipeable (plan D4: `mj sync push --format=json | jq .errors`).
  * - **MD mode**: the result is emitted as a fenced ```json block on stdout
  *   (forward-looking slot for AI chat UIs, plan D10).
+ *
+ * Chrome (spinners, color) additionally requires a real TTY, not just text mode:
+ * `--format=text > log.txt` should not write spinner escape codes into the file.
  */
 export declare class MJCLIRuntimeHost implements IMJCLIRuntimeHost {
     readonly Format: OutputFormat;
     readonly Verbose: boolean;
+    readonly Interactive: boolean;
     private readonly noBanner;
+    /** Whether stdout is a real terminal — gates spinners, color, and pretty-printing. */
+    private readonly stdoutIsTTY;
     /** Process-start, used for the "· N total" running clock in text mode. */
     private readonly startTime;
     private spinner;
     private stepBaseMessage;
     private stepStart;
     private ticker;
-    constructor(format?: OutputFormat, verbose?: boolean, noBanner?: boolean);
-    /** Spinners/colors are only appropriate in text mode on a real TTY. */
+    constructor(format?: OutputFormat, verbose?: boolean, noBanner?: boolean, options?: RuntimeHostOptions);
+    /**
+     * Spinners/colors are only appropriate in text mode on a real TTY. A piped text
+     * run still logs — it just logs plain lines instead of animating.
+     */
     private get textMode();
+    /** Text mode regardless of whether stdout is a terminal — gates plain-line logging. */
+    private get plainTextMode();
     private fmtMs;
     private stopTicker;
     /**

package/dist/runtime-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-host.d.ts","sourceRoot":"","sources":["../src/runtime-host.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGnG;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAiB,YAAW,iBAAiB;IACxD,SAAgB,MAAM,EAAE,YAAY,CAAC;IACrC,SAAgB,OAAO,EAAE,OAAO,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IAEnC,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IAExC,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,eAAe,CAAM;IAC7B,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,MAAM,CAA+B;gBAEjC,MAAM,GAAE,YAAqB,EAAE,OAAO,UAAQ,EAAE,QAAQ,UAAQ;IAS5E,uEAAuE;IACvE,OAAO,KAAK,QAAQ,GAEnB;IAED,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,UAAU;IAOlB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAenB,mFAAmF;IACnF,OAAO,CAAC,eAAe;IAIhB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAW9B,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAU/B,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAejD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAc9C,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,QAAiB,GAAG,IAAI;IAapD,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAezC,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;CAWvC"}
+{"version":3,"file":"runtime-host.d.ts","sourceRoot":"","sources":["../src/runtime-host.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAInG,kGAAkG;AAClG,MAAM,WAAW,kBAAkB;IACjC,kGAAkG;IAClG,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,0CAA0C;IAC1C,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,gBAAiB,YAAW,iBAAiB;IACxD,SAAgB,MAAM,EAAE,YAAY,CAAC;IACrC,SAAgB,OAAO,EAAE,OAAO,CAAC;IACjC,SAAgB,WAAW,EAAE,OAAO,CAAC;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,sFAAsF;IACtF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;IAEtC,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IAExC,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,eAAe,CAAM;IAC7B,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,MAAM,CAA+B;gBAEjC,MAAM,GAAE,YAAqB,EAAE,OAAO,UAAQ,EAAE,QAAQ,UAAQ,EAAE,OAAO,GAAE,kBAAuB;IAW9G;;;OAGG;IACH,OAAO,KAAK,QAAQ,GAEnB;IAED,uFAAuF;IACvF,OAAO,KAAK,aAAa,GAExB;IAED,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,UAAU;IAOlB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAenB,mFAAmF;IACnF,OAAO,CAAC,eAAe;IAIhB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAW9B,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAU/B,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAiBjD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAgB9C,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,QAAiB,GAAG,IAAI;IAiBpD,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAezC,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;CAYvC"}

package/dist/runtime-host.js

@@ -1,6 +1,7 @@
 import ora from 'ora-classic';
 import chalk from 'chalk';
 import { SerializeResult } from './serialize.js';
+import { ShouldSuppressChrome } from './output-format.js';
 /**
  * Default implementation of {@link IMJCLIRuntimeHost}.
  *
@@ -15,9 +16,12 @@ import { SerializeResult } from './serialize.js';
  *   pipeable (plan D4: `mj sync push --format=json | jq .errors`).
  * - **MD mode**: the result is emitted as a fenced ```json block on stdout
  *   (forward-looking slot for AI chat UIs, plan D10).
+ *
+ * Chrome (spinners, color) additionally requires a real TTY, not just text mode:
+ * `--format=text > log.txt` should not write spinner escape codes into the file.
  */
 export class MJCLIRuntimeHost {
-    constructor(format = 'text', verbose = false, noBanner = false) {
+    constructor(format = 'text', verbose = false, noBanner = false, options = {}) {
         /** Process-start, used for the "· N total" running clock in text mode. */
         this.startTime = Date.now();
         this.spinner = null;
@@ -26,13 +30,22 @@ export class MJCLIRuntimeHost {
         this.ticker = null;
         this.Format = format;
         this.Verbose = verbose;
+        this.Interactive = options.interactive ?? false;
+        this.stdoutIsTTY = options.stdoutIsTTY ?? process.stdout.isTTY === true;
         // `--no-banner` is handled globally by the CLI prerun hook (it strips the flag
         // from argv so not-yet-migrated commands don't fail oclif's strict parser) and
         // signalled here via env, so honor either source.
         this.noBanner = noBanner || process.env.MJ_CLI_NO_BANNER === '1';
     }
-    /** Spinners/colors are only appropriate in text mode on a real TTY. */
+    /**
+     * Spinners/colors are only appropriate in text mode on a real TTY. A piped text
+     * run still logs — it just logs plain lines instead of animating.
+     */
     get textMode() {
+        return this.Format === 'text' && !ShouldSuppressChrome(this.Format, this.stdoutIsTTY);
+    }
+    /** Text mode regardless of whether stdout is a terminal — gates plain-line logging. */
+    get plainTextMode() {
         return this.Format === 'text';
     }
     fmtMs(ms) {
@@ -106,6 +119,9 @@ export class MJCLIRuntimeHost {
         else if (this.Format === 'json') {
             this.emitStderrEvent({ event: 'step-done', label, detail });
         }
+        else if (this.plainTextMode) {
+            process.stdout.write(`${detail ? `${label} ${detail}` : label}\n`);
+        }
     }
     FailStep(label, detail) {
         this.stopTicker();
@@ -121,6 +137,9 @@ export class MJCLIRuntimeHost {
         else if (this.Format === 'json') {
             this.emitStderrEvent({ event: 'step-failed', label, detail });
         }
+        else if (this.plainTextMode) {
+            process.stderr.write(`${detail ? `${label} ${detail}` : label}\n`);
+        }
     }
     Log(message, level = 'info') {
         if (this.textMode) {
@@ -131,6 +150,11 @@ export class MJCLIRuntimeHost {
             // eslint-disable-next-line no-console
             (level === 'error' ? console.error : console.log)(painted);
         }
+        else if (this.plainTextMode) {
+            // Text mode, piped: still the caller's primary output, so keep it on stdout —
+            // just uncolored, since escape codes in a redirected file help nobody.
+            (level === 'error' ? process.stderr : process.stdout).write(message + '\n');
+        }
         else {
             // Keep stdout clean for the JSON/MD result — all human logging → stderr.
             process.stderr.write(message + '\n');
@@ -145,7 +169,7 @@ export class MJCLIRuntimeHost {
         if (this.Format === 'json') {
             this.emitStderrEvent({ event: 'start', command: usage.command, runtime: usage.runtime });
         }
-        else if (this.textMode) {
+        else if (this.plainTextMode) {
             const r = usage.runtime;
             const secs = r.typicalSeconds ? `~${r.typicalSeconds}s` : r.class;
             const note = r.note ? ` — ${r.note}` : '';
@@ -157,7 +181,8 @@ export class MJCLIRuntimeHost {
         if (this.spinner?.isSpinning)
             this.spinner.stop();
         if (this.Format === 'json' || this.Format === 'md') {
-            process.stdout.write(SerializeResult(result, this.Format) + '\n');
+            // Pretty only when a human is watching; a pipe gets one compact line.
+            process.stdout.write(SerializeResult(result, this.Format, { pretty: this.stdoutIsTTY }) + '\n');
         }
         // Text mode: the plugin is responsible for its own rich human output (via
         // Log/StartStep/SucceedStep). Emit deliberately prints nothing extra so we

package/dist/runtime-host.js.map

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

package/dist/serialize.d.ts

@@ -1,10 +1,26 @@
-import type { MJCLIResult, OutputFormat } from './types.js';
+import { type MJCLIResult, type OutputFormat } from './types.js';
+/** Options for {@link SerializeResult}. */
+export interface SerializeOptions {
+    /**
+     * Pretty-print with 2-space indent. Defaults to false.
+     *
+     * The caller passes `true` only when a human is looking at the output — i.e.
+     * stdout is a TTY. A piped consumer gets one compact line instead: `jq` reads it
+     * identically, it appends cleanly to an NDJSON log, and it costs an agent
+     * meaningfully fewer tokens to carry in context.
+     */
+    pretty?: boolean;
+}
 /**
  * Single source of truth for serializing an {@link MJCLIResult} per format.
  * Both the runtime host's `Emit` and the usage commands call this so JSON/MD
  * envelopes are always rendered identically. Returns the empty string for
  * `text` — in text mode the plugin renders its own human output, not a result
  * blob. No trailing newline; callers add one.
+ *
+ * Always stamps {@link MJ_CLI_RESULT_VERSION} (respecting an explicit `version`
+ * already on the result), so every machine-readable envelope on the wire carries
+ * a contract version even though constructing one doesn't require it.
  */
-export declare function SerializeResult(result: MJCLIResult, format: OutputFormat): string;
+export declare function SerializeResult(result: MJCLIResult, format: OutputFormat, options?: SerializeOptions): string;
 //# sourceMappingURL=serialize.d.ts.map

package/dist/serialize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,CAIjF"}
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAErF,2CAA2C;AAC3C,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAYjH"}

package/dist/serialize.js

@@ -1,15 +1,26 @@
+import { MJ_CLI_RESULT_VERSION } from './types.js';
 /**
  * Single source of truth for serializing an {@link MJCLIResult} per format.
  * Both the runtime host's `Emit` and the usage commands call this so JSON/MD
  * envelopes are always rendered identically. Returns the empty string for
  * `text` — in text mode the plugin renders its own human output, not a result
  * blob. No trailing newline; callers add one.
+ *
+ * Always stamps {@link MJ_CLI_RESULT_VERSION} (respecting an explicit `version`
+ * already on the result), so every machine-readable envelope on the wire carries
+ * a contract version even though constructing one doesn't require it.
  */
-export function SerializeResult(result, format) {
-    if (format === 'json')
-        return JSON.stringify(result, null, 2);
-    if (format === 'md')
-        return '```json\n' + JSON.stringify(result, null, 2) + '\n```';
-    return '';
+export function SerializeResult(result, format, options = {}) {
+    if (format === 'text')
+        return '';
+    // `version` is listed first so it leads the rendered envelope; the spread can carry
+    // an explicit `version: undefined`, so re-assert the default after it.
+    const versioned = { version: MJ_CLI_RESULT_VERSION, ...result };
+    if (!versioned.version)
+        versioned.version = MJ_CLI_RESULT_VERSION;
+    // `md` is read by a human in a chat UI, so it is always pretty regardless.
+    const indent = format === 'md' || options.pretty ? 2 : 0;
+    const body = JSON.stringify(versioned, null, indent);
+    return format === 'md' ? '```json\n' + body + '\n```' : body;
 }
 //# sourceMappingURL=serialize.js.map

package/dist/serialize.js.map

@@ -1 +1 @@
-{"version":3,"file":"serialize.js","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,MAAmB,EAAE,MAAoB;IACvE,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC9D,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC;IACpF,OAAO,EAAE,CAAC;AACZ,CAAC"}
+{"version":3,"file":"serialize.js","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAuC,MAAM,SAAS,CAAC;AAerF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,MAAmB,EAAE,MAAoB,EAAE,UAA4B,EAAE;IACvG,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,EAAE,CAAC;IAEjC,oFAAoF;IACpF,uEAAuE;IACvE,MAAM,SAAS,GAAgB,EAAE,OAAO,EAAE,qBAAqB,EAAE,GAAG,MAAM,EAAE,CAAC;IAC7E,IAAI,CAAC,SAAS,CAAC,OAAO;QAAE,SAAS,CAAC,OAAO,GAAG,qBAAqB,CAAC;IAClE,2EAA2E;IAC3E,MAAM,MAAM,GAAG,MAAM,KAAK,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAErD,OAAO,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/D,CAAC"}

package/dist/types.d.ts

@@ -58,11 +58,54 @@ export interface PluginUsage {
     examples?: string[];
     runtime: RuntimeHint;
 }
+/**
+ * Version of the {@link MJCLIResult} wire contract. Bump on any breaking change to
+ * the envelope so an agent that cached a shape can detect the drift instead of
+ * silently mis-parsing. Stamped onto every serialized result by `SerializeResult`.
+ */
+export declare const MJ_CLI_RESULT_VERSION = "1";
+/**
+ * Stable, machine-readable error codes. An agent branches on these; the human-facing
+ * `message` is free to be reworded without breaking anyone.
+ *
+ * Add cases here rather than inventing ad-hoc strings at a call site — the whole
+ * point is that the set is enumerable and greppable.
+ */
+export declare const MJCLIErrorCodes: {
+    /** A needed value was missing and the run wasn't allowed to prompt for it. */
+    readonly NonInteractive: "E_NON_INTERACTIVE";
+    /** No `mj.config.cjs` (or equivalent) found. */
+    readonly NoConfig: "E_NO_CONFIG";
+    /** A flag/argument combination the command can't act on. */
+    readonly InvalidArguments: "E_INVALID_ARGS";
+    /** A referenced entity, directory, or record doesn't exist. */
+    readonly NotFound: "E_NOT_FOUND";
+    /** Input failed the command's own validation pass. */
+    readonly ValidationFailed: "E_VALIDATION_FAILED";
+    /** Database connect/query failure. */
+    readonly DatabaseError: "E_DATABASE";
+    /** Anything not yet categorized. Prefer a specific code. */
+    readonly Unknown: "E_UNKNOWN";
+};
+/** Union of the values in {@link MJCLIErrorCodes}. */
+export type MJCLIErrorCode = (typeof MJCLIErrorCodes)[keyof typeof MJCLIErrorCodes];
 /** A single failure, collected (not interleaved) so an agent can read them as a list. */
 export interface MJCLIResultError {
     /** Entity name, file path, phase — whatever is relevant. */
     context?: string;
     message: string;
+    /**
+     * Stable code from {@link MJCLIErrorCodes}. Optional only so existing call sites
+     * keep compiling — new code should always set it, because without one an agent
+     * has nothing to branch on but a regex over `message`.
+     */
+    code?: MJCLIErrorCode;
+    /**
+     * Concrete remediation the caller can act on unaided — name the flag, the file,
+     * the command to run. "Invalid configuration" is not a suggestion;
+     * "Run `mj sync init` in this directory first." is.
+     */
+    suggestion?: string;
 }
 /**
  * Universal result shape every plugin returns (plan D6). Command-specific detail
@@ -70,6 +113,11 @@ export interface MJCLIResultError {
  * {@link MJCLIResult.errors} with full detail (not just a count).
  */
 export interface MJCLIResult {
+    /**
+     * {@link MJ_CLI_RESULT_VERSION}. Optional on construction — `SerializeResult`
+     * stamps it — so it is always present on the wire and never a burden at a call site.
+     */
+    version?: string;
     success: boolean;
     /** 'sync:push', 'codegen', 'migrate', etc. */
     command: string;
@@ -88,6 +136,12 @@ export interface IMJCLIRuntimeHost {
     readonly Format: OutputFormat;
     /** Whether `--verbose` was set. */
     readonly Verbose: boolean;
+    /**
+     * Whether this run may prompt — true at a real terminal, false when piped, spawned,
+     * or running in CI, unless `--interactive` / `--no-interactive` overrides it. Plugins
+     * read this to choose between asking and failing fast with the flag to pass.
+     */
+    readonly Interactive: boolean;
     StartStep(label: string): void;
     UpdateStep(label: string): void;
     SucceedStep(label: string, detail?: string): void;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAElD,kDAAkD;AAClD,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,UAAU,CAAC;IACjD,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,eAAe,EAAE,CAAC;IAC1B,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,yFAAyF;AACzF,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAG1B,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAG/C,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAE7C;;;;OAIG;IACH,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAE1C,gEAAgE;IAChE,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;CACjC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAElD,kDAAkD;AAClD,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,UAAU,CAAC;IACjD,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,eAAe,EAAE,CAAC;IAC1B,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,eAAe;IAC1B,8EAA8E;;IAE9E,gDAAgD;;IAEhD,4DAA4D;;IAE5D,+DAA+D;;IAE/D,sDAAsD;;IAEtD,sCAAsC;;IAEtC,4DAA4D;;CAEpD,CAAC;AAEX,sDAAsD;AACtD,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AAEpF,yFAAyF;AACzF,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAG9B,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAG/C,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAE7C;;;;OAIG;IACH,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAE1C,gEAAgE;IAChE,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;CACjC"}

package/dist/types.js

@@ -5,5 +5,33 @@
  * and the {@link IMJCLIRuntimeHost} renders it per the active {@link OutputFormat}.
  * No `ora`, `chalk`, or `console` calls live inside a plugin's business logic.
  */
-export {};
+/**
+ * Version of the {@link MJCLIResult} wire contract. Bump on any breaking change to
+ * the envelope so an agent that cached a shape can detect the drift instead of
+ * silently mis-parsing. Stamped onto every serialized result by `SerializeResult`.
+ */
+export const MJ_CLI_RESULT_VERSION = '1';
+/**
+ * Stable, machine-readable error codes. An agent branches on these; the human-facing
+ * `message` is free to be reworded without breaking anyone.
+ *
+ * Add cases here rather than inventing ad-hoc strings at a call site — the whole
+ * point is that the set is enumerable and greppable.
+ */
+export const MJCLIErrorCodes = {
+    /** A needed value was missing and the run wasn't allowed to prompt for it. */
+    NonInteractive: 'E_NON_INTERACTIVE',
+    /** No `mj.config.cjs` (or equivalent) found. */
+    NoConfig: 'E_NO_CONFIG',
+    /** A flag/argument combination the command can't act on. */
+    InvalidArguments: 'E_INVALID_ARGS',
+    /** A referenced entity, directory, or record doesn't exist. */
+    NotFound: 'E_NOT_FOUND',
+    /** Input failed the command's own validation pass. */
+    ValidationFailed: 'E_VALIDATION_FAILED',
+    /** Database connect/query failure. */
+    DatabaseError: 'E_DATABASE',
+    /** Anything not yet categorized. Prefer a specific code. */
+    Unknown: 'E_UNKNOWN',
+};
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA4DH;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,8EAA8E;IAC9E,cAAc,EAAE,mBAAmB;IACnC,gDAAgD;IAChD,QAAQ,EAAE,aAAa;IACvB,4DAA4D;IAC5D,gBAAgB,EAAE,gBAAgB;IAClC,+DAA+D;IAC/D,QAAQ,EAAE,aAAa;IACvB,sDAAsD;IACtD,gBAAgB,EAAE,qBAAqB;IACvC,sCAAsC;IACtC,aAAa,EAAE,YAAY;IAC3B,4DAA4D;IAC5D,OAAO,EAAE,WAAW;CACZ,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/cli-core",
   "type": "module",
-  "version": "6.1.0-edge.3",
+  "version": "6.1.0-edge.5",
   "description": "Pluggable MJ CLI core — BaseCLIPlugin, runtime host, and progressive-disclosure usage primitives shared by mj CLI plugins",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,7 +14,7 @@
   "author": "MemberJunction",
   "license": "BUSL-1.1",
   "dependencies": {
-    "@memberjunction/global": "6.1.0-edge.3",
+    "@memberjunction/global": "6.1.0-edge.5",
     "@oclif/core": "^3.27.0",
     "chalk": "^5.6.2",
     "ora-classic": "^5.4.2"