@memberjunction/cli-core 0.0.1 → 5.42.0

package/README.md

@@ -1,45 +1,138 @@
 # @memberjunction/cli-core
 
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@memberjunction/cli-core`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+Pluggable core for the MemberJunction `mj` CLI. Provides the primitives that let
+commands be **machine-readable**, **discoverable**, and **pluggable** — so AI
+coding agents (Claude Code, OpenCode, …) can drive `mj` reliably, and third
+parties can add commands without modifying MJCLI.
+
+## Why
+
+`mj codegen`, `mj sync push/pull`, etc. are run constantly by humans *and* AI
+agents. Humans get clean spinners and a summary box. Agents get four problems:
+
+1. **No machine-readable output** — parsing chalk + box-drawing is fragile.
+2. **Errors interleaved mid-run** — no collected error list.
+3. **The banner burns context** — hundreds of captured chars before content.
+4. **No runtime signal** — agents pick a timeout and kill healthy long-running
+   commands (`codegen`, `migrate`) midway.
+
+This package fixes all four with one architecture, and makes the CLI open to
+third-party plugins as a side effect.
+
+## Architecture
+
+> **Principle:** plugins return *data* (`MJCLIResult`); the host *renders* it.
+> No `ora`, `chalk`, or `console` inside a plugin's `Execute()`.
+
+```
+mj (oclif root)
+ ├─ loads mj-cli-plugins.json → @RegisterClass populates ClassFactory
+ ├─ composes `mj usage` / `mj <domain> usage` from each plugin's static Usage
+ └─ routes a command → BaseCLIPlugin subclass
+        │  injects MJCLIRuntimeHost (per --format)
+        ▼
+   BaseCLIPlugin                         MJCLIRuntimeHost
+   - abstract Execute(): MJCLIResult     - text: ora spinner + chalk
+   - this.Host.StartStep / Log / …       - json: events→stderr, result→stdout
+   - declares static Usage               - md:   fenced ```json block
+```
+
+## Output formats (`--format`)
+
+| Format | Result destination | Decorative output | Use |
+|---|---|---|---|
+| `text` (default) | — (plugin renders) | stdout (spinners/chalk) | humans |
+| `json` | **stdout** (clean JSON) | **stderr** (`{event:…}`) | agents, `\| jq` |
+| `md` | stdout (fenced block) | stderr | AI chat UIs |
+
+`--verbose` / `--no-banner` are inherited by every plugin too.
+
+## Progressive-disclosure usage (for agents)
+
+```bash
+mj usage --format=json | jq '.data.domains[].domain'        # tier 1 (~200 tokens)
+mj sync usage --format=json | jq '.data.commands[].runtime' # tier 2 (one domain)
+mj sync push --help                                         # tier 3 (full oclif help)
+```
+
+Tier 1 returns a domain map; tier 2 returns one domain's commands, flags,
+examples, and **runtime hints**. The guidance string tells the agent to check
+usage rather than guess flags. An agent discovers the surface in ~500–700 tokens
+instead of pulling the whole ~13k command tree.
+
+## Runtime hints / timeouts
+
+Every plugin declares a `RuntimeHint` (`fast` <5s · `moderate` 5–60s · `slow`
+>60s · `variable`). It's surfaced two ways so agents budget timeouts:
+
+1. In usage output (read before invoking).
+2. As a pre-execution advisory — `{event:'start', command, runtime}` on stderr
+   (JSON mode) or a dim note (text). Suppressed for `fast` commands.
+
+```bash
+timeout_s=$(mj codegen usage --format=json | jq '.data.commands[0].runtime.typicalSeconds')
+```
+
+## Authoring a plugin
+
+1. Create a package that depends on `@memberjunction/cli-core`.
+2. Subclass `BaseCLIPlugin`, register it, declare flags + `static Usage`, and
+   implement `Execute()`:
+
+```typescript
+import { Flags } from '@oclif/core';
+import { RegisterClass } from '@memberjunction/global';
+import { BaseCLIPlugin, type MJCLIResult, type PluginUsage } from '@memberjunction/cli-core';
+
+@RegisterClass(BaseCLIPlugin, 'widgets:build')
+export class WidgetsBuildPlugin extends BaseCLIPlugin {
+  static description = 'Build widgets';
+  static flags = { dir: Flags.string({ description: 'Source directory' }) };
+
+  static Usage: PluginUsage = {
+    domain: 'widgets',
+    command: 'widgets:build',
+    summary: 'Compile widgets from source.',
+    flags: [{ name: '--dir', type: 'string', description: 'Source directory' }],
+    examples: ['mj widgets build --dir=src', 'mj widgets build --format=json'],
+    runtime: { class: 'moderate', typicalSeconds: 20, note: 'scales with widget count' },
+  };
+
+  protected async Execute(): Promise<MJCLIResult> {
+    const start = Date.now();
+    const { flags } = await this.parse(WidgetsBuildPlugin);
+    this.Host.StartStep('Building widgets');
+    // … do work; collect errors instead of throwing …
+    this.Host.SucceedStep('Built widgets');
+    if (this.Host.Format === 'text') this.Host.Log('Done.');   // human-only rich text
+    return { success: true, command: 'widgets:build', durationSeconds: (Date.now() - start) / 1000, data: { /* … */ } };
+  }
+
+  // Optional: release resources / force-exit to kill lingering handles.
+  protected async Cleanup(result: MJCLIResult): Promise<void> { /* close pools */ }
+}
+```
+
+3. Ship the plugin behind a **light subpath** (e.g. `@my-org/pkg/plugins`) that
+   static-imports only `cli-core` + light deps and dynamic-imports any heavy
+   engine inside `Execute()`. This keeps oclif manifest generation and `mj usage`
+   enumeration cheap.
+
+4. Register it so `mj` loads it:
+
+```bash
+mj plugin add @my-org/pkg/plugins
+# appends to mj-cli-plugins.json — no MJCLI change needed
+```
+
+In the MemberJunction monorepo, MJCLI also keeps a one-line oclif shim under
+`src/commands/` (`export { WidgetsBuildPlugin as default } from '…'`) so oclif
+discovers and routes the command. The plugin's logic stays in its home package.
+
+## Exports
+
+- `BaseCLIPlugin` — abstract base (extends oclif `Command`).
+- `MJCLIRuntimeHost` / `IMJCLIRuntimeHost` — the stdio host.
+- `CLIPluginRegistry` — loads `mj-cli-plugins.json`, composes tier-1/tier-2 usage.
+- Types: `MJCLIResult`, `OutputFormat`, `PluginUsage`, `RuntimeHint`, …
+- `PLUGIN_CONFIG_FILENAME` — `"mj-cli-plugins.json"`.

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

@@ -0,0 +1,56 @@
+import { Command } from '@oclif/core';
+import type { IMJCLIRuntimeHost, MJCLIResult, PluginUsage } from './types.js';
+/**
+ * Abstract base for every pluggable `mj` command (plan D1/D2).
+ *
+ * Extends oclif's {@link Command}, so oclif still owns flag parsing, help
+ * generation, and routing. We wrap only the *execution* layer: subclasses
+ * implement {@link BaseCLIPlugin.Execute} (pure logic, returns data) and the
+ * 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).
+ */
+export declare abstract class BaseCLIPlugin extends Command {
+    /** Inherited by every subclass through oclif's static `baseFlags` mechanism. */
+    static baseFlags: {
+        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>;
+    };
+    /**
+     * Every plugin declares its own usage + runtime metadata. The CLI root reads
+     * this off the registered classes to assemble the progressive-disclosure
+     * `mj usage` / `mj <domain> usage` surface and the timeout advisory.
+     * Subclasses MUST override.
+     */
+    static Usage: PluginUsage;
+    protected Host: IMJCLIRuntimeHost;
+    /** Parsed flags, captured once in {@link run}; read via {@link GetFlags}. */
+    private parsedFlags;
+    /**
+     * The flags parsed for this command. Subclasses call this in {@link Execute}
+     * instead of re-parsing — the parse happens once, in {@link run}.
+     *
+     * The `as unknown as T` is the ONE place the cross-package `@oclif/core` copy
+     * split is bridged: cli-core nests its own oclif, so the inferred parse type
+     * isn't nameable from a strict consumer package (TS2742). Confining the cast
+     * here keeps every plugin's `Execute()` cast-free. Pass
+     * `Interfaces.InferredFlags<typeof YourPlugin.flags>` as `T`.
+     */
+    protected GetFlags<T>(): T;
+    /**
+     * oclif entry point — do NOT override in subclasses. Override {@link Execute}.
+     */
+    run(): Promise<void>;
+    /**
+     * Optional post-Emit hook. Override to release resources (DB pools, singletons)
+     * and, when necessary, `process.exit()` to terminate lingering background work.
+     */
+    protected Cleanup(_result: MJCLIResult): Promise<void>;
+    /** Subclasses implement this — pure logic, no direct stdio. */
+    protected abstract Execute(): Promise<MJCLIResult>;
+}
+//# sourceMappingURL=base-cli-plugin.d.ts.map

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

@@ -0,0 +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"}

package/dist/base-cli-plugin.js

@@ -0,0 +1,78 @@
+import { Command, Flags } from '@oclif/core';
+import { MJCLIRuntimeHost } from './runtime-host.js';
+/**
+ * Abstract base for every pluggable `mj` command (plan D1/D2).
+ *
+ * Extends oclif's {@link Command}, so oclif still owns flag parsing, help
+ * generation, and routing. We wrap only the *execution* layer: subclasses
+ * implement {@link BaseCLIPlugin.Execute} (pure logic, returns data) and the
+ * 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).
+ */
+export class BaseCLIPlugin extends Command {
+    /** 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)',
+        }),
+        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' }),
+    }; }
+    /**
+     * The flags parsed for this command. Subclasses call this in {@link Execute}
+     * instead of re-parsing — the parse happens once, in {@link run}.
+     *
+     * The `as unknown as T` is the ONE place the cross-package `@oclif/core` copy
+     * split is bridged: cli-core nests its own oclif, so the inferred parse type
+     * isn't nameable from a strict consumer package (TS2742). Confining the cast
+     * here keeps every plugin's `Execute()` cast-free. Pass
+     * `Interfaces.InferredFlags<typeof YourPlugin.flags>` as `T`.
+     */
+    GetFlags() {
+        return this.parsedFlags;
+    }
+    /**
+     * oclif entry point — do NOT override in subclasses. Override {@link Execute}.
+     */
+    async run() {
+        // Parse against the concrete subclass so `baseFlags` + the subclass `flags`
+        // both resolve. `this.constructor` is the concrete command class at runtime.
+        const ctor = this.constructor;
+        const { flags } = await this.parse(ctor);
+        this.parsedFlags = flags;
+        const f = flags;
+        const format = f.format ?? 'text';
+        const verbose = !!f.verbose;
+        const noBanner = !!f['no-banner'];
+        this.Host = new MJCLIRuntimeHost(format, verbose, noBanner);
+        // 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();
+        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.
+        await this.Cleanup(result);
+        // Default exit handling. Plugins that must force-exit to kill lingering
+        // handles (e.g. embedding workers) do so inside Cleanup().
+        if (!result.success) {
+            this.exit(1);
+        }
+    }
+    /**
+     * Optional post-Emit hook. Override to release resources (DB pools, singletons)
+     * and, when necessary, `process.exit()` to terminate lingering background work.
+     */
+    async Cleanup(_result) {
+        // no-op by default
+    }
+}
+//# sourceMappingURL=base-cli-plugin.js.map

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

@@ -0,0 +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"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './types.js';
+export { MJCLIRuntimeHost } from './runtime-host.js';
+export { BaseCLIPlugin } from './base-cli-plugin.js';
+export { SerializeResult } from './serialize.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

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from './types.js';
+export { MJCLIRuntimeHost } from './runtime-host.js';
+export { BaseCLIPlugin } from './base-cli-plugin.js';
+export { SerializeResult } from './serialize.js';
+export { CLIPluginRegistry, PLUGIN_CONFIG_FILENAME, } from './plugin-registry.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/dist/plugin-registry.d.ts

@@ -0,0 +1,72 @@
+import type { MJCLIResult, PluginUsage, RuntimeHint } from './types.js';
+/** Filename enumerating active plugin entry points (plan §4 / D8). */
+export declare const PLUGIN_CONFIG_FILENAME = "mj-cli-plugins.json";
+/** Outcome of {@link CLIPluginRegistry.LoadPluginsFromConfig}. */
+export interface PluginLoadResult {
+    /** Specifiers that imported successfully. */
+    loaded: string[];
+    /** Specifiers that failed to import, with the error, so callers can log them. */
+    failed: Array<{
+        specifier: string;
+        error: string;
+    }>;
+}
+/** Tier-1 domain map entry. */
+export interface UsageDomainSummary {
+    domain: string;
+    summary: string;
+    runtime: RuntimeHint['class'];
+}
+/** Tier-1 result payload. */
+export interface UsageDomainMap {
+    guidance: string;
+    domains: UsageDomainSummary[];
+}
+/** Tier-2 result payload (one domain's commands). */
+export interface UsageDomainDetail {
+    domain: string;
+    commands: PluginUsage[];
+}
+/**
+ * Loads CLI plugin packages and composes the progressive-disclosure usage surface
+ * (`mj usage` → `mj <domain> usage`) dynamically from each registered plugin's
+ * `static Usage` (plan §5, the linearis model). There is no central hardcoded
+ * help file — usage is whatever plugins are loaded, including third-party ones.
+ */
+export declare class CLIPluginRegistry {
+    /**
+     * Walks up from {@link startDir} looking for `mj-cli-plugins.json`, then
+     * dynamic-imports each listed entry point so its `@RegisterClass(BaseCLIPlugin, …)`
+     * decorators populate the ClassFactory. Safe to call repeatedly — imports are
+     * cached by the module loader. Returns the list of specifiers it loaded.
+     */
+    static LoadPluginsFromConfig(startDir?: string): Promise<PluginLoadResult>;
+    /**
+     * Resolves a plugin entry point. Package specifiers (`@scope/pkg`,
+     * `@scope/pkg/plugins`) import as-is; relative paths resolve against the config
+     * file's directory and convert to a file URL for ESM import.
+     */
+    private static importSpecifier;
+    /** First `mj-cli-plugins.json` found walking up from {@link startDir}. */
+    private static findConfig;
+    /** Every registered plugin's usage metadata, de-duplicated by command key. */
+    static GetAllUsage(): PluginUsage[];
+    /** Tier-1: the domain map — each domain + one-line summary + runtime class. */
+    static BuildDomainMap(): UsageDomainMap;
+    /** Tier-2: every command in {@link domain} with summary, flags, examples, runtime. */
+    static BuildDomainDetail(domain: string): UsageDomainDetail;
+    /** Wraps a tier payload in the universal {@link MJCLIResult} shape. */
+    static AsResult(command: string, data: Record<string, unknown>): MJCLIResult;
+    /**
+     * A domain summary: if a single command's summary best represents the domain
+     * use it; otherwise join the command summaries compactly.
+     */
+    private static domainSummary;
+    /**
+     * The "loosest" runtime class across a domain's commands, so an agent setting a
+     * single domain-wide timeout errs on the generous side.
+     * Ordering: variable > slow > moderate > fast.
+     */
+    private static domainRuntimeClass;
+}
+//# sourceMappingURL=plugin-registry.d.ts.map

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

@@ -0,0 +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,8EAA8E;IAC9E,MAAM,CAAC,WAAW,IAAI,WAAW,EAAE;IAYnC,+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"}

package/dist/plugin-registry.js

@@ -0,0 +1,152 @@
+import { existsSync, readFileSync } from 'fs';
+import { dirname, isAbsolute, resolve } from 'path';
+import { pathToFileURL } from 'url';
+import { MJGlobal } from '@memberjunction/global';
+import { BaseCLIPlugin } from './base-cli-plugin.js';
+/** Filename enumerating active plugin entry points (plan §4 / D8). */
+export const PLUGIN_CONFIG_FILENAME = 'mj-cli-plugins.json';
+const GUIDANCE = 'Run `mj <domain> usage` before invoking. Do NOT guess flags or subcommands.';
+/**
+ * Loads CLI plugin packages and composes the progressive-disclosure usage surface
+ * (`mj usage` → `mj <domain> usage`) dynamically from each registered plugin's
+ * `static Usage` (plan §5, the linearis model). There is no central hardcoded
+ * help file — usage is whatever plugins are loaded, including third-party ones.
+ */
+export class CLIPluginRegistry {
+    /**
+     * Walks up from {@link startDir} looking for `mj-cli-plugins.json`, then
+     * dynamic-imports each listed entry point so its `@RegisterClass(BaseCLIPlugin, …)`
+     * decorators populate the ClassFactory. Safe to call repeatedly — imports are
+     * cached by the module loader. Returns the list of specifiers it loaded.
+     */
+    static async LoadPluginsFromConfig(startDir = process.cwd()) {
+        const result = { loaded: [], failed: [] };
+        const configPath = this.findConfig(startDir);
+        if (!configPath)
+            return result;
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(configPath, 'utf-8'));
+        }
+        catch (e) {
+            result.failed.push({ specifier: configPath, error: `Invalid ${PLUGIN_CONFIG_FILENAME}: ${e instanceof Error ? e.message : String(e)}` });
+            return result;
+        }
+        const specifiers = Array.isArray(parsed.plugins) ? parsed.plugins : [];
+        const configDir = dirname(configPath);
+        for (const specifier of specifiers) {
+            try {
+                await this.importSpecifier(specifier, configDir);
+                result.loaded.push(specifier);
+            }
+            catch (e) {
+                // A broken/optional plugin must not take down the whole CLI; record the
+                // failure so the caller can surface it under --verbose rather than
+                // swallowing it silently.
+                result.failed.push({ specifier, error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        return result;
+    }
+    /**
+     * Resolves a plugin entry point. Package specifiers (`@scope/pkg`,
+     * `@scope/pkg/plugins`) import as-is; relative paths resolve against the config
+     * file's directory and convert to a file URL for ESM import.
+     */
+    static async importSpecifier(specifier, configDir) {
+        if (specifier.startsWith('.') || isAbsolute(specifier)) {
+            const abs = isAbsolute(specifier) ? specifier : resolve(configDir, specifier);
+            await import(pathToFileURL(abs).href);
+        }
+        else {
+            await import(specifier);
+        }
+    }
+    /** First `mj-cli-plugins.json` found walking up from {@link startDir}. */
+    static findConfig(startDir) {
+        let dir = resolve(startDir);
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const candidate = resolve(dir, PLUGIN_CONFIG_FILENAME);
+            if (existsSync(candidate))
+                return candidate;
+            const parent = dirname(dir);
+            if (parent === dir)
+                return null;
+            dir = parent;
+        }
+    }
+    /** Every registered plugin's usage metadata, de-duplicated by command key. */
+    static GetAllUsage() {
+        const regs = MJGlobal.Instance.ClassFactory.GetAllRegistrations(BaseCLIPlugin);
+        const byCommand = new Map();
+        for (const reg of regs) {
+            const usage = reg.SubClass?.Usage;
+            if (usage?.domain && usage?.command && !byCommand.has(usage.command)) {
+                byCommand.set(usage.command, usage);
+            }
+        }
+        return [...byCommand.values()];
+    }
+    /** Tier-1: the domain map — each domain + one-line summary + runtime class. */
+    static BuildDomainMap() {
+        const usages = this.GetAllUsage();
+        const byDomain = new Map();
+        for (const u of usages) {
+            const list = byDomain.get(u.domain) ?? [];
+            list.push(u);
+            byDomain.set(u.domain, list);
+        }
+        const domains = [...byDomain.entries()]
+            .map(([domain, cmds]) => ({
+            domain,
+            summary: this.domainSummary(domain, cmds),
+            runtime: this.domainRuntimeClass(cmds),
+        }))
+            .sort((a, b) => a.domain.localeCompare(b.domain));
+        return { guidance: GUIDANCE, domains };
+    }
+    /** Tier-2: every command in {@link domain} with summary, flags, examples, runtime. */
+    static BuildDomainDetail(domain) {
+        const target = domain.trim().toLowerCase();
+        const commands = this.GetAllUsage()
+            .filter((u) => u.domain.toLowerCase() === target)
+            .sort((a, b) => a.command.localeCompare(b.command));
+        return { domain, commands };
+    }
+    /** Wraps a tier payload in the universal {@link MJCLIResult} shape. */
+    static AsResult(command, data) {
+        return { success: true, command, durationSeconds: 0, data };
+    }
+    /**
+     * A domain summary: if a single command's summary best represents the domain
+     * use it; otherwise join the command summaries compactly.
+     */
+    static domainSummary(domain, cmds) {
+        if (cmds.length === 1)
+            return cmds[0].summary;
+        // Prefer a command whose key equals the domain (e.g. 'codegen').
+        const headline = cmds.find((c) => c.command === domain);
+        if (headline)
+            return headline.summary;
+        // Avoid a run-on line for 3+ commands: lead with the first summary + a count.
+        if (cmds.length >= 3)
+            return `${cmds[0].summary} (+${cmds.length - 1} more commands)`;
+        return cmds.map((c) => c.summary).join(' ');
+    }
+    /**
+     * The "loosest" runtime class across a domain's commands, so an agent setting a
+     * single domain-wide timeout errs on the generous side.
+     * Ordering: variable > slow > moderate > fast.
+     */
+    static domainRuntimeClass(cmds) {
+        const order = ['fast', 'moderate', 'slow', 'variable'];
+        let worst = 'fast';
+        for (const c of cmds) {
+            if (order.indexOf(c.runtime.class) > order.indexOf(worst))
+                worst = c.runtime.class;
+        }
+        return worst;
+    }
+}
+//# sourceMappingURL=plugin-registry.js.map

package/dist/plugin-registry.js.map

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

package/dist/runtime-host.d.ts

@@ -0,0 +1,48 @@
+import type { IMJCLIRuntimeHost, LogLevel, MJCLIResult, OutputFormat, PluginUsage } from './types.js';
+/**
+ * Default implementation of {@link IMJCLIRuntimeHost}.
+ *
+ * - **Text mode** (default): an `ora` spinner with a live elapsed timer for steps,
+ *   chalk-colored logs, and a generic human summary on {@link MJCLIRuntimeHost.Emit}
+ *   when the plugin hasn't already rendered its own. Plugins that want rich,
+ *   command-specific text (e.g. a push summary box) build the string themselves
+ *   and pass it through {@link MJCLIRuntimeHost.Log} — the host never hard-codes
+ *   per-command formatting.
+ * - **JSON mode**: every decorative call (steps, logs, runtime advisory) goes to
+ *   **stderr** so the {@link MJCLIResult} JSON on **stdout** stays clean and
+ *   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).
+ */
+export declare class MJCLIRuntimeHost implements IMJCLIRuntimeHost {
+    readonly Format: OutputFormat;
+    readonly Verbose: boolean;
+    private readonly noBanner;
+    /** 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. */
+    private get textMode();
+    private fmtMs;
+    private stopTicker;
+    /**
+     * Begin the live elapsed timer for the current step. Each call resets the
+     * clock so the timer reflects the CURRENT step. Unref'd so it never holds the
+     * event loop open on its own.
+     */
+    private startTicker;
+    /** Structured progress event on stderr (JSON mode) so stdout stays result-only. */
+    private emitStderrEvent;
+    StartStep(label: string): void;
+    UpdateStep(label: string): void;
+    SucceedStep(label: string, detail?: string): void;
+    FailStep(label: string, detail?: string): void;
+    Log(message: string, level?: LogLevel): void;
+    AnnounceRuntime(usage: PluginUsage): void;
+    Emit(result: MJCLIResult): void;
+}
+//# sourceMappingURL=runtime-host.d.ts.map

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

@@ -0,0 +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"}

package/dist/runtime-host.js

@@ -0,0 +1,167 @@
+import ora from 'ora-classic';
+import chalk from 'chalk';
+import { SerializeResult } from './serialize.js';
+/**
+ * Default implementation of {@link IMJCLIRuntimeHost}.
+ *
+ * - **Text mode** (default): an `ora` spinner with a live elapsed timer for steps,
+ *   chalk-colored logs, and a generic human summary on {@link MJCLIRuntimeHost.Emit}
+ *   when the plugin hasn't already rendered its own. Plugins that want rich,
+ *   command-specific text (e.g. a push summary box) build the string themselves
+ *   and pass it through {@link MJCLIRuntimeHost.Log} — the host never hard-codes
+ *   per-command formatting.
+ * - **JSON mode**: every decorative call (steps, logs, runtime advisory) goes to
+ *   **stderr** so the {@link MJCLIResult} JSON on **stdout** stays clean and
+ *   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).
+ */
+export class MJCLIRuntimeHost {
+    constructor(format = 'text', verbose = false, noBanner = false) {
+        /** Process-start, used for the "· N total" running clock in text mode. */
+        this.startTime = Date.now();
+        this.spinner = null;
+        this.stepBaseMessage = '';
+        this.stepStart = 0;
+        this.ticker = null;
+        this.Format = format;
+        this.Verbose = verbose;
+        // `--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. */
+    get textMode() {
+        return this.Format === 'text';
+    }
+    fmtMs(ms) {
+        return ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
+    }
+    stopTicker() {
+        if (this.ticker) {
+            clearInterval(this.ticker);
+            this.ticker = null;
+        }
+    }
+    /**
+     * Begin the live elapsed timer for the current step. Each call resets the
+     * clock so the timer reflects the CURRENT step. Unref'd so it never holds the
+     * event loop open on its own.
+     */
+    startTicker(message) {
+        this.stopTicker();
+        this.stepBaseMessage = message;
+        this.stepStart = Date.now();
+        if (this.spinner) {
+            this.ticker = setInterval(() => {
+                if (!this.spinner)
+                    return;
+                const step = this.fmtMs(Date.now() - this.stepStart);
+                const total = this.fmtMs(Date.now() - this.startTime);
+                this.spinner.text = `${this.stepBaseMessage} ${chalk.gray(`· ${step} · ${total} total`)}`;
+            }, 100);
+            this.ticker.unref?.();
+        }
+    }
+    /** Structured progress event on stderr (JSON mode) so stdout stays result-only. */
+    emitStderrEvent(event) {
+        process.stderr.write(JSON.stringify(event) + '\n');
+    }
+    StartStep(label) {
+        if (this.textMode) {
+            if (!this.spinner)
+                this.spinner = ora();
+            this.spinner.start(label);
+            this.startTicker(label);
+        }
+        else if (this.Format === 'json') {
+            this.emitStderrEvent({ event: 'step', label });
+        }
+        // md mode: steps are noise in a fenced block — suppress.
+    }
+    UpdateStep(label) {
+        if (this.textMode) {
+            if (!this.spinner)
+                this.spinner = ora();
+            this.spinner.text = label;
+            this.startTicker(label);
+        }
+        else if (this.Format === 'json') {
+            this.emitStderrEvent({ event: 'step', label });
+        }
+    }
+    SucceedStep(label, detail) {
+        this.stopTicker();
+        if (this.textMode) {
+            const elapsed = this.stepStart ? chalk.gray(` (${this.fmtMs(Date.now() - this.stepStart)})`) : '';
+            const text = detail ? `${label} ${chalk.gray(detail)}${elapsed}` : `${label}${elapsed}`;
+            if (this.spinner) {
+                this.spinner.stopAndPersist({ symbol: chalk.green('✓'), text });
+            }
+            else {
+                process.stdout.write(`${chalk.green('✓')} ${text}\n`);
+            }
+        }
+        else if (this.Format === 'json') {
+            this.emitStderrEvent({ event: 'step-done', label, detail });
+        }
+    }
+    FailStep(label, detail) {
+        this.stopTicker();
+        if (this.textMode) {
+            const text = detail ? `${label} ${chalk.gray(detail)}` : label;
+            if (this.spinner) {
+                this.spinner.fail(text);
+            }
+            else {
+                process.stderr.write(`${chalk.red('✗')} ${text}\n`);
+            }
+        }
+        else if (this.Format === 'json') {
+            this.emitStderrEvent({ event: 'step-failed', label, detail });
+        }
+    }
+    Log(message, level = 'info') {
+        if (this.textMode) {
+            // A spinner mid-render would garble a raw write; stop it first.
+            if (this.spinner?.isSpinning)
+                this.spinner.stop();
+            const painted = level === 'error' ? chalk.red(message) : level === 'warn' ? chalk.yellow(message) : message;
+            // eslint-disable-next-line no-console
+            (level === 'error' ? console.error : console.log)(painted);
+        }
+        else {
+            // Keep stdout clean for the JSON/MD result — all human logging → stderr.
+            process.stderr.write(message + '\n');
+        }
+    }
+    AnnounceRuntime(usage) {
+        // Fast commands don't warrant an advisory — it would just be noise.
+        if (!usage?.runtime || usage.runtime.class === 'fast')
+            return;
+        if (this.noBanner)
+            return;
+        if (this.Format === 'json') {
+            this.emitStderrEvent({ event: 'start', command: usage.command, runtime: usage.runtime });
+        }
+        else if (this.textMode) {
+            const r = usage.runtime;
+            const secs = r.typicalSeconds ? `~${r.typicalSeconds}s` : r.class;
+            const note = r.note ? ` — ${r.note}` : '';
+            process.stderr.write(chalk.gray(`⏱  ${usage.command}: typically ${secs} (${r.class})${note}\n`));
+        }
+    }
+    Emit(result) {
+        this.stopTicker();
+        if (this.spinner?.isSpinning)
+            this.spinner.stop();
+        if (this.Format === 'json' || this.Format === 'md') {
+            process.stdout.write(SerializeResult(result, this.Format) + '\n');
+        }
+        // Text mode: the plugin is responsible for its own rich human output (via
+        // Log/StartStep/SucceedStep). Emit deliberately prints nothing extra so we
+        // never double-render a summary.
+    }
+}
+//# sourceMappingURL=runtime-host.js.map

package/dist/runtime-host.js.map

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

package/dist/serialize.d.ts

@@ -0,0 +1,10 @@
+import type { MJCLIResult, OutputFormat } 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.
+ */
+export declare function SerializeResult(result: MJCLIResult, format: OutputFormat): string;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/serialize.d.ts.map

@@ -0,0 +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"}

package/dist/serialize.js

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ */
+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 '';
+}
+//# sourceMappingURL=serialize.js.map

package/dist/serialize.js.map

@@ -0,0 +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"}

package/dist/types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Core type definitions for the pluggable MJ CLI.
+ *
+ * The guiding principle (plan D2): plugins return *data* — a {@link MJCLIResult} —
+ * and the {@link IMJCLIRuntimeHost} renders it per the active {@link OutputFormat}.
+ * No `ora`, `chalk`, or `console` calls live inside a plugin's business logic.
+ */
+/**
+ * Output format selected via the global `--format` flag.
+ * - `text`: human-readable (the default; spinners + chalk).
+ * - `json`: machine-readable result on stdout, decorative output on stderr.
+ * - `md`: Markdown-fenced result block, for AI chat UIs (forward-looking, plan D10).
+ */
+export type OutputFormat = 'text' | 'json' | 'md';
+/** Severity for {@link IMJCLIRuntimeHost.Log}. */
+export type LogLevel = 'info' | 'warn' | 'error';
+/**
+ * How long a command typically runs, so an AI agent wrapping `mj` in a shell
+ * timeout can budget correctly rather than killing a healthy long-running
+ * command midway (plan §1d / D12).
+ */
+export interface RuntimeHint {
+    /**
+     * - `fast`: <5s (no start advisory emitted).
+     * - `moderate`: 5–60s.
+     * - `slow`: >60s.
+     * - `variable`: depends on scope — see {@link RuntimeHint.note}.
+     */
+    class: 'fast' | 'moderate' | 'slow' | 'variable';
+    /** Best-guess midpoint (seconds) an agent can use to set a timeout. */
+    typicalSeconds?: number;
+    /** e.g. 'scales with entity count', 'full migration ≫ incremental'. */
+    note?: string;
+}
+/** One flag described in a plugin's usage metadata. */
+export interface PluginUsageFlag {
+    name: string;
+    type: string;
+    description: string;
+}
+/**
+ * Per-plugin usage + runtime metadata. Drives the progressive-disclosure
+ * `mj usage` (tier 1) and `mj <domain> usage` (tier 2) surface and the timeout
+ * advisory (plan §5). Co-located with the plugin so it can never drift from the
+ * actual flags.
+ */
+export interface PluginUsage {
+    /** Groups commands in `mj usage` — e.g. 'sync', 'codegen', 'migrate'. */
+    domain: string;
+    /** The invocation key — e.g. 'sync:push', 'codegen', 'migrate'. */
+    command: string;
+    /** One line, shown in the `mj usage` domain map. Keep it terse. */
+    summary: string;
+    /** Fuller prose, shown only in `mj <domain> usage`. */
+    description?: string;
+    flags?: PluginUsageFlag[];
+    /** Copy-pasteable invocations. */
+    examples?: string[];
+    runtime: RuntimeHint;
+}
+/** 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;
+}
+/**
+ * Universal result shape every plugin returns (plan D6). Command-specific detail
+ * goes in the typed {@link MJCLIResult.data} field; failures always go in
+ * {@link MJCLIResult.errors} with full detail (not just a count).
+ */
+export interface MJCLIResult {
+    success: boolean;
+    /** 'sync:push', 'codegen', 'migrate', etc. */
+    command: string;
+    durationSeconds: number;
+    data?: Record<string, unknown>;
+    errors?: MJCLIResultError[];
+    warnings?: string[];
+}
+/**
+ * The runtime host abstracts all stdio. A plugin talks to the host through this
+ * interface; the host decides whether a call becomes a spinner line, a JSON event
+ * on stderr, or nothing — based on the active {@link OutputFormat}.
+ */
+export interface IMJCLIRuntimeHost {
+    /** The active output format. Plugins gate human-only text rendering on this. */
+    readonly Format: OutputFormat;
+    /** Whether `--verbose` was set. */
+    readonly Verbose: boolean;
+    StartStep(label: string): void;
+    UpdateStep(label: string): void;
+    SucceedStep(label: string, detail?: string): void;
+    FailStep(label: string, detail?: string): void;
+    Log(message: string, level?: LogLevel): void;
+    /**
+     * Runtime advisory, emitted before work starts so an agent can budget its
+     * timeout (plan §5/§6). Text mode: a dim one-liner on stderr. JSON mode: a
+     * `{event:'start', ...}` line on stderr. Suppressed for `fast` commands.
+     */
+    AnnounceRuntime(usage: PluginUsage): void;
+    /** Final result — host serializes per the active `--format`. */
+    Emit(result: MJCLIResult): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +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"}

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * Core type definitions for the pluggable MJ CLI.
+ *
+ * The guiding principle (plan D2): plugins return *data* — a {@link MJCLIResult} —
+ * 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 {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/package.json

@@ -1,10 +1,43 @@
 {
   "name": "@memberjunction/cli-core",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @memberjunction/cli-core",
+  "type": "module",
+  "version": "5.42.0",
+  "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",
+  "scripts": {
+    "build": "tsc && tsc-alias -f",
+    "watch": "tsc --watch",
+    "clean": "rimraf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+    "memberjunction",
+    "cli",
+    "oclif",
+    "plugin"
+  ],
+  "author": "MemberJunction",
+  "license": "ISC",
+  "dependencies": {
+    "@memberjunction/global": "5.42.0",
+    "@oclif/core": "^3.27.0",
+    "chalk": "^5.6.2",
+    "ora-classic": "^5.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.11",
+    "rimraf": "6.1.2",
+    "tsc-alias": "^1.8.10",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MemberJunction/MJ"
+  }
 }