@memberjunction/cli 2.118.0 → 2.120.0

package/README.md

@@ -209,6 +209,7 @@ Available AI commands:
 - `actions run` - Execute an AI action with parameters
 - `prompts list` - List available AI models for direct prompt execution
 - `prompts run` - Execute a direct prompt with an AI model
+- `audit agent-run` - Audit and analyze AI agent execution runs for debugging
 
 **📚 For detailed documentation:** See the [AI-CLI README](../AI/AICLI/README.md)
 
@@ -248,6 +249,21 @@ mj ai prompts run -p "Explain quantum computing in simple terms"
 # Use a specific model
 mj ai prompts run -p "Write a Python function to sort a list" --model "gpt-4"
 
+# Audit recent agent runs
+mj ai audit agent-run --list --status failed --days 7
+
+# Audit specific run with summary
+mj ai audit agent-run <run-id>
+
+# Examine specific step in detail
+mj ai audit agent-run <run-id> --step 3 --detail full
+
+# Analyze errors in a run
+mj ai audit agent-run <run-id> --errors
+
+# Export full audit data
+mj ai audit agent-run <run-id> --export full --file audit.json
+
 # Use system prompt and temperature
 mj ai prompts run -p "Generate a haiku" --system "You are a poet" --temperature 0.3
 ```
@@ -281,6 +297,22 @@ mj ai prompts run -p "Generate a haiku" --system "You are a poet" --temperature
 - `-v, --verbose`: Show detailed execution information
 - `--timeout <ms>`: Execution timeout in milliseconds (default: 300000)
 
+**Audit Commands:**
+- `<run-id>`: Agent Run ID (UUID) to audit (optional for --list mode)
+- `-l, --list`: List recent agent runs (filter with other options)
+- `-a, --agent <name>`: Filter by agent name (requires --list)
+- `--status <status>`: Filter by status: success, failed, running, all (default: all)
+- `--days <number>`: Number of days to look back (default: 7)
+- `--limit <number>`: Maximum runs to return (default: 50)
+- `-s, --step <number>`: Show details for specific step (1-based index)
+- `-d, --detail <level>`: Detail level for step: minimal, standard, detailed, full (default: standard)
+- `-e, --errors`: Show only error details and context
+- `--export <type>`: Export data: full, summary, steps
+- `-f, --file <path>`: Output file path for export
+- `--max-tokens <number>`: Max tokens per field (default: 5000, 0 = no limit)
+- `-o, --output <format>`: Output format (compact, json, table, markdown)
+- `-v, --verbose`: Show detailed diagnostic information
+
 #### AI Features:
 
 **Progress Tracking**: Real-time visual progress indicators during agent execution
@@ -299,6 +331,15 @@ mj ai prompts run -p "Generate a haiku" --system "You are a poet" --temperature
 - Natural back-and-forth dialogue
 - Exit with "exit", "quit", or Ctrl+C
 
+**Agent Run Auditing**: Comprehensive debugging and analysis tools
+- List recent runs with filtering by agent, status, and date
+- View run summaries with performance metrics and step breakdowns
+- Deep dive into specific steps with smart truncation for large payloads
+- Automatic error pattern detection with suggested fixes
+- Multiple output formats including markdown for AI assistants
+- Export capabilities for offline analysis
+- Optimized for read-only performance with `simple` result type
+
 #### AI Configuration:
 
 Add AI-specific settings to your `mj.config.cjs`:
@@ -451,6 +492,7 @@ mj dbdoc [COMMAND] [OPTIONS]
 Available dbdoc commands:
 - `init` - Initialize a new DBAutoDoc project
 - `analyze` - Analyze database and generate documentation
+- `generate-queries` - Generate sample SQL queries from existing analysis state
 - `export` - Export documentation in multiple formats (SQL, Markdown, HTML, CSV, Mermaid)
 - `status` - Show analysis status and progress
 - `reset` - Reset analysis state
@@ -472,6 +514,14 @@ mj dbdoc analyze --resume ./output/run-6/state.json
 # Use custom config
 mj dbdoc analyze --config ./my-config.json
 
+# Generate sample SQL queries from existing state
+mj dbdoc generate-queries --from-state ./output/run-1/state.json
+
+# Generate with custom settings
+mj dbdoc generate-queries --from-state ./output/run-1/state.json \
+  --queries-per-table 10 \
+  --output-dir ./queries
+
 # Export all formats
 mj dbdoc export --sql --markdown --html --csv --mermaid
 
@@ -504,6 +554,13 @@ mj dbdoc reset --force
 - `-r, --resume <path>`: Resume from an existing state file
 - `-c, --config <path>`: Path to config file (default: ./config.json)
 
+**Generate Queries Command:**
+- `--from-state <path>`: Path to existing state.json file from previous analysis (required)
+- `--output-dir <path>`: Output directory for generated queries (optional)
+- `-c, --config <path>`: Path to config file for database connection and AI settings (default: ./config.json)
+- `--queries-per-table <number>`: Number of queries to generate per table (optional, overrides config)
+- `--max-execution-time <ms>`: Maximum execution time for query validation in milliseconds (optional, overrides config)
+
 **Export Command:**
 - `-s, --state-file <path>`: Path to state JSON file
 - `-o, --output-dir <path>`: Output directory for generated files
@@ -541,6 +598,7 @@ mj dbdoc reset --force
 
 **Advanced Features:**
 - 🔍 **Relationship Discovery** - Detect missing primary and foreign keys
+- 🎯 **Sample Query Generation** - Generate reference SQL queries for AI agent training with alignment tracking
 - 🛡️ **Granular Guardrails** - Multi-level resource controls
 - ⏸️ **Resume Capability** - Pause and resume from checkpoint
 - 📦 **Programmatic API** - Use as a library in your applications
@@ -552,6 +610,41 @@ mj dbdoc reset --force
 - CSV Exports (spreadsheet-ready)
 - Mermaid Diagrams (standalone ERD files)
 - Analysis Reports (detailed metrics)
+- Sample Queries (JSON with SQL, metadata, and alignment tracking)
+
+**Sample Query Generation:**
+
+DBAutoDoc can generate reference SQL queries that solve the **query alignment problem** where multi-query patterns (summary + detail) have inconsistent filtering logic. These "gold standard" queries include:
+- Explicit filtering rules for consistency
+- Alignment tracking via `relatedQueryIds`
+- Query patterns (Summary+Detail, Multi-Entity Drilldown, Time Series)
+- Validated, executable SQL
+- Perfect for few-shot prompting in AI agents like Skip
+
+Enable in config:
+```json
+{
+  "analysis": {
+    "sampleQueryGeneration": {
+      "enabled": true,
+      "queriesPerTable": 5,
+      "includeMultiQueryPatterns": true,
+      "validateAlignment": true
+    }
+  }
+}
+```
+
+Or generate separately from existing state:
+```bash
+mj dbdoc generate-queries --from-state ./output/run-1/state.json
+```
+
+**Use Cases:**
+- Training AI agents to generate consistent multi-query patterns
+- Creating reference examples for few-shot prompting
+- Documenting common query patterns for your database
+- Validating that related queries use consistent filtering logic
 
 ---
 

package/dist/commands/ai/audit/agent-run.d.ts

@@ -0,0 +1,24 @@
+import { Command } from '@oclif/core';
+export default class AgentRun extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        output: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        step: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        detail: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        errors: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        list: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        agent: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        status: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        days: import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
+        limit: import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
+        export: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        file: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'max-tokens': import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
+        verbose: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    static args: {
+        runId: import("@oclif/core/lib/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/ai/audit/agent-run.js

@@ -0,0 +1,213 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const ai_cli_1 = require("@memberjunction/ai-cli");
+const ora_classic_1 = __importDefault(require("ora-classic"));
+const chalk_1 = __importDefault(require("chalk"));
+const fs = __importStar(require("fs/promises"));
+class AgentRun extends core_1.Command {
+    static description = 'Audit and analyze AI agent execution runs for debugging and performance analysis';
+    static examples = [
+        // Summary mode
+        '<%= config.bin %> <%= command.id %> abc-123-def-456',
+        '<%= config.bin %> <%= command.id %> abc-123-def-456 --output=markdown',
+        // Step detail mode
+        '<%= config.bin %> <%= command.id %> abc-123-def-456 --step 3',
+        '<%= config.bin %> <%= command.id %> abc-123-def-456 --step 3 --detail full',
+        // Error analysis
+        '<%= config.bin %> <%= command.id %> abc-123-def-456 --errors',
+        // List recent runs
+        '<%= config.bin %> <%= command.id %> --list --agent "Skip: Requirements Expert"',
+        '<%= config.bin %> <%= command.id %> --list --status failed --days 7',
+        // Export mode
+        '<%= config.bin %> <%= command.id %> abc-123-def-456 --export full --file report.json',
+    ];
+    static flags = {
+        // Output format
+        output: core_1.Flags.string({
+            char: 'o',
+            description: 'Output format',
+            options: ['compact', 'json', 'table', 'markdown'],
+            default: 'compact',
+        }),
+        // Step detail mode
+        step: core_1.Flags.integer({
+            char: 's',
+            description: 'Show details for specific step number (1-based index)',
+            exclusive: ['list', 'errors'],
+        }),
+        detail: core_1.Flags.string({
+            char: 'd',
+            description: 'Detail level for step output (default: standard)',
+            options: ['minimal', 'standard', 'detailed', 'full'],
+            dependsOn: ['step'],
+        }),
+        // Error analysis mode
+        errors: core_1.Flags.boolean({
+            char: 'e',
+            description: 'Show only error details and context',
+            default: false,
+            exclusive: ['step', 'list'],
+        }),
+        // List mode
+        list: core_1.Flags.boolean({
+            char: 'l',
+            description: 'List recent agent runs',
+            default: false,
+            exclusive: ['step', 'errors'],
+        }),
+        agent: core_1.Flags.string({
+            char: 'a',
+            description: 'Filter by agent name',
+            dependsOn: ['list'],
+        }),
+        status: core_1.Flags.string({
+            description: 'Filter by run status',
+            options: ['success', 'failed', 'running', 'all'],
+            default: 'all',
+            dependsOn: ['list'],
+        }),
+        days: core_1.Flags.integer({
+            description: 'Number of days to look back',
+            default: 7,
+            dependsOn: ['list'],
+        }),
+        limit: core_1.Flags.integer({
+            description: 'Maximum number of runs to return',
+            default: 50,
+            dependsOn: ['list'],
+        }),
+        // Export mode
+        export: core_1.Flags.string({
+            description: 'Export full data to file',
+            options: ['full', 'summary', 'steps'],
+            dependsOn: ['file'],
+        }),
+        file: core_1.Flags.string({
+            char: 'f',
+            description: 'Output file path for export',
+        }),
+        // Truncation control
+        'max-tokens': core_1.Flags.integer({
+            description: 'Maximum tokens per field (0 = no limit)',
+            default: 5000,
+        }),
+        // Verbose mode
+        verbose: core_1.Flags.boolean({
+            char: 'v',
+            description: 'Show detailed diagnostic information',
+            default: false,
+        }),
+    };
+    static args = {
+        runId: core_1.Args.string({
+            description: 'AI Agent Run ID to audit (UUID)',
+            required: false, // Optional because --list mode doesn't need it
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(AgentRun);
+        const spinner = (0, ora_classic_1.default)();
+        try {
+            const service = new ai_cli_1.AgentAuditService();
+            // MODE 1: List recent runs
+            if (flags.list) {
+                spinner.start('Loading recent agent runs...');
+                const runs = await service.listRecentRuns({
+                    agentName: flags.agent,
+                    status: flags.status,
+                    days: flags.days,
+                    limit: flags.limit,
+                });
+                spinner.stop();
+                this.log(service.formatRunList(runs, flags.output));
+                process.exit(0);
+                return;
+            }
+            // Validate runId for non-list modes
+            if (!args.runId) {
+                this.error('Run ID is required (use --list to see recent runs)');
+            }
+            // MODE 2: Step detail mode
+            if (flags.step != null) {
+                spinner.start(`Loading step ${flags.step} details...`);
+                const stepDetail = await service.getStepDetail(args.runId, flags.step, {
+                    detailLevel: (flags.detail || 'standard'),
+                    maxTokens: flags['max-tokens'],
+                });
+                spinner.stop();
+                this.log(service.formatStepDetail(stepDetail, flags.output));
+                process.exit(0);
+                return;
+            }
+            // MODE 3: Error analysis mode
+            if (flags.errors) {
+                spinner.start('Analyzing errors...');
+                const errorAnalysis = await service.analyzeErrors(args.runId);
+                spinner.stop();
+                this.log(service.formatErrorAnalysis(errorAnalysis, flags.output));
+                process.exit(0);
+                return;
+            }
+            // MODE 4: Export mode
+            if (flags.export && flags.file) {
+                spinner.start('Exporting full audit data...');
+                const exportData = await service.exportRun(args.runId, flags.export);
+                await fs.writeFile(flags.file, JSON.stringify(exportData, null, 2), 'utf8');
+                spinner.stop();
+                this.log(chalk_1.default.green(`✓ Full audit data exported to ${flags.file}`));
+                this.log(chalk_1.default.dim(`  File size: ${(JSON.stringify(exportData).length / 1024).toFixed(1)} KB`));
+                process.exit(0);
+                return;
+            }
+            // MODE 5: Summary mode (default)
+            spinner.start('Loading agent run summary...');
+            const summary = await service.getRunSummary(args.runId, {
+                includeStepList: true,
+                maxTokens: flags['max-tokens'],
+            });
+            spinner.stop();
+            this.log(service.formatRunSummary(summary, flags.output));
+            if (flags.verbose) {
+                this.log(chalk_1.default.dim('\n💡 Tip: Use --step <N> to see details for a specific step'));
+                this.log(chalk_1.default.dim('💡 Tip: Use --errors to see only error information'));
+            }
+            process.exit(0);
+        }
+        catch (error) {
+            spinner.fail('Audit failed');
+            if (flags.verbose && error instanceof Error) {
+                this.log(chalk_1.default.red('\nError Details:'));
+                this.log(error.stack || error.message);
+            }
+            this.error(error);
+        }
+    }
+}
+exports.default = AgentRun;

package/dist/commands/ai/audit/index.d.ts

@@ -0,0 +1,6 @@
+import { Command } from '@oclif/core';
+export default class Audit extends Command {
+    static description: string;
+    static hidden: boolean;
+    run(): Promise<void>;
+}

package/dist/commands/ai/audit/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+class Audit extends core_1.Command {
+    static description = 'Analyze and audit AI agent runs, prompts, and actions for debugging and performance analysis';
+    static hidden = false;
+    async run() {
+        // This command just displays help for the audit topic
+        await this.config.runCommand('help', ['ai', 'audit']);
+    }
+}
+exports.default = Audit;

package/dist/commands/clean/index.js

@@ -20,10 +20,8 @@ class Clean extends core_1.Command {
     async run() {
         const parsed = await this.parse(Clean);
         this.flags = parsed.flags;
-        if (!config_1.config) {
-            this.error('No configuration found');
-        }
-        const flywayConfig = await (0, config_1.getFlywayConfig)(config_1.config);
+        const config = (0, config_1.getValidatedConfig)();
+        const flywayConfig = await (0, config_1.getFlywayConfig)(config);
         const flyway = new node_flyway_1.Flyway(flywayConfig);
         this.log('Resetting MJ database to pre-installation state');
         this.log('Note that users and roles have not been dropped');

package/dist/commands/dbdoc/analyze.js

@@ -46,7 +46,7 @@ class DbDocAnalyze extends core_1.Command {
     async run() {
         const { flags } = await this.parse(DbDocAnalyze);
         // Load DBAutoDoc command dynamically
-        const { default: AnalyzeCommand } = await Promise.resolve().then(() => __importStar(require('@memberjunction/db-auto-doc/dist/commands/analyze.js')));
+        const { default: AnalyzeCommand } = await Promise.resolve().then(() => __importStar(require('@memberjunction/db-auto-doc/dist/commands/analyze')));
         // Build args array for DBAutoDoc command
         const args = [];
         if (flags.resume) {

package/dist/commands/dbdoc/export.js

@@ -78,7 +78,7 @@ class DbDocExport extends core_1.Command {
     async run() {
         const { flags } = await this.parse(DbDocExport);
         // Load DBAutoDoc command dynamically
-        const { default: ExportCommand } = await Promise.resolve().then(() => __importStar(require('@memberjunction/db-auto-doc/dist/commands/export.js')));
+        const { default: ExportCommand } = await Promise.resolve().then(() => __importStar(require('@memberjunction/db-auto-doc/dist/commands/export')));
         // Build args array for DBAutoDoc command
         const args = [];
         if (flags['state-file'])

package/dist/commands/dbdoc/generate-queries.d.ts

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+export default class DbDocGenerateQueries extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'from-state': import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'output-dir': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        config: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'queries-per-table': import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'max-execution-time': import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/dbdoc/generate-queries.js

@@ -0,0 +1,82 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+class DbDocGenerateQueries extends core_1.Command {
+    static description = 'Generate sample SQL queries from existing analysis state (delegates to db-auto-doc generate-queries)';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --from-state ./output/run-1/state.json',
+        '<%= config.bin %> <%= command.id %> --from-state ./output/run-1/state.json --output-dir ./queries',
+        '<%= config.bin %> <%= command.id %> --from-state ./output/run-1/state.json --queries-per-table 10',
+    ];
+    static flags = {
+        'from-state': core_1.Flags.string({
+            description: 'Path to existing state.json file from previous analysis',
+            required: true
+        }),
+        'output-dir': core_1.Flags.string({
+            description: 'Output directory for generated queries',
+            required: false
+        }),
+        config: core_1.Flags.string({
+            char: 'c',
+            description: 'Path to config file (for database connection and AI settings)',
+            default: './config.json'
+        }),
+        'queries-per-table': core_1.Flags.integer({
+            description: 'Number of queries to generate per table',
+            required: false
+        }),
+        'max-execution-time': core_1.Flags.integer({
+            description: 'Maximum execution time for query validation (ms)',
+            required: false
+        })
+    };
+    async run() {
+        const { flags } = await this.parse(DbDocGenerateQueries);
+        // Load DBAutoDoc command dynamically
+        const { default: GenerateQueriesCommand } = await Promise.resolve().then(() => __importStar(require('@memberjunction/db-auto-doc/dist/commands/generate-queries')));
+        // Build args array for DBAutoDoc command
+        const args = [];
+        if (flags['from-state']) {
+            args.push('--from-state', flags['from-state']);
+        }
+        if (flags['output-dir']) {
+            args.push('--output-dir', flags['output-dir']);
+        }
+        if (flags.config) {
+            args.push('--config', flags.config);
+        }
+        if (flags['queries-per-table']) {
+            args.push('--queries-per-table', flags['queries-per-table'].toString());
+        }
+        if (flags['max-execution-time']) {
+            args.push('--max-execution-time', flags['max-execution-time'].toString());
+        }
+        // Execute the DBAutoDoc generate-queries command
+        await GenerateQueriesCommand.run(args);
+    }
+}
+exports.default = DbDocGenerateQueries;

package/dist/commands/dbdoc/init.js

@@ -31,7 +31,7 @@ class DbDocInit extends core_1.Command {
     ];
     async run() {
         // Load DBAutoDoc command dynamically
-        const { default: InitCommand } = await Promise.resolve().then(() => __importStar(require('@memberjunction/db-auto-doc/dist/commands/init.js')));
+        const { default: InitCommand } = await Promise.resolve().then(() => __importStar(require('@memberjunction/db-auto-doc/dist/commands/init')));
         // Execute the DBAutoDoc init command
         await InitCommand.run([]);
     }

package/dist/commands/dbdoc/reset.js

@@ -40,7 +40,7 @@ class DbDocReset extends core_1.Command {
     async run() {
         const { flags } = await this.parse(DbDocReset);
         // Load DBAutoDoc command dynamically
-        const { default: ResetCommand } = await Promise.resolve().then(() => __importStar(require('@memberjunction/db-auto-doc/dist/commands/reset.js')));
+        const { default: ResetCommand } = await Promise.resolve().then(() => __importStar(require('@memberjunction/db-auto-doc/dist/commands/reset')));
         // Build args array for DBAutoDoc command
         const args = [];
         if (flags.force) {

package/dist/commands/dbdoc/status.js

@@ -39,7 +39,7 @@ class DbDocStatus extends core_1.Command {
     async run() {
         const { flags } = await this.parse(DbDocStatus);
         // Load DBAutoDoc command dynamically
-        const { default: StatusCommand } = await Promise.resolve().then(() => __importStar(require('@memberjunction/db-auto-doc/dist/commands/status.js')));
+        const { default: StatusCommand } = await Promise.resolve().then(() => __importStar(require('@memberjunction/db-auto-doc/dist/commands/status')));
         // Build args array for DBAutoDoc command
         const args = [];
         if (flags['state-file']) {

package/dist/commands/migrate/index.js

@@ -19,14 +19,12 @@ class Migrate extends core_1.Command {
     };
     async run() {
         const { flags } = await this.parse(Migrate);
-        if (!config_1.config) {
-            this.error('No configuration found');
-        }
-        const flywayConfig = await (0, config_1.getFlywayConfig)(config_1.config, flags.tag);
+        const config = (0, config_1.getValidatedConfig)();
+        const flywayConfig = await (0, config_1.getFlywayConfig)(config, flags.tag);
         const flyway = new node_flyway_1.Flyway(flywayConfig);
         if (flags.verbose) {
             this.log(`Connecting to ${flywayConfig.url}`);
-            this.log(`Migrating ${config_1.config.coreSchema} schema using migrations from:\n\t- ${flywayConfig.migrationLocations.join('\n\t- ')}\n`);
+            this.log(`Migrating ${config.coreSchema} schema using migrations from:\n\t- ${flywayConfig.migrationLocations.join('\n\t- ')}\n`);
         }
         if (flags.tag) {
             this.log(`Migrating to ${flags.tag}`);

package/dist/config.d.ts

@@ -47,18 +47,22 @@ export declare const config: {
     coreSchema: string;
     mjRepoUrl: string;
 } | undefined;
-export declare const updatedConfig: () => {
-    cleanDisabled: boolean;
-    dbHost: string;
-    dbDatabase: string;
-    dbPort: number;
-    codeGenLogin: string;
-    codeGenPassword: string;
-    migrationsLocation: string;
-    dbTrustServerCertificate: boolean;
-    coreSchema: string;
-    mjRepoUrl: string;
-} | undefined;
+/**
+ * Get validated config for commands that require database connection.
+ * Throws error if config is invalid.
+ */
+export declare const getValidatedConfig: () => MJConfig;
+/**
+ * Get optional config for commands that don't require database connection.
+ * Returns undefined if no config exists, or partial config if it exists.
+ */
+export declare const getOptionalConfig: () => Partial<MJConfig> | undefined;
+/**
+ * Legacy function for backward compatibility with codegen.
+ * Validates and returns updated config.
+ * Returns undefined silently if config is invalid (command will handle the error).
+ */
+export declare const updatedConfig: () => MJConfig | undefined;
 export declare const createFlywayUrl: (mjConfig: MJConfig) => string;
 export declare const getFlywayConfig: (mjConfig: MJConfig, tag?: string) => Promise<FlywayConfig>;
 export {};

package/dist/config.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getFlywayConfig = exports.createFlywayUrl = exports.updatedConfig = exports.config = void 0;
+exports.getFlywayConfig = exports.createFlywayUrl = exports.updatedConfig = exports.getOptionalConfig = exports.getValidatedConfig = exports.config = void 0;
 const cosmiconfig_1 = require("cosmiconfig");
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
@@ -9,6 +9,7 @@ const zod_1 = require("zod");
 const MJ_REPO_URL = 'https://github.com/MemberJunction/MJ.git';
 const explorer = (0, cosmiconfig_1.cosmiconfigSync)('mj', { searchStrategy: 'global' });
 const result = explorer.search(process.cwd());
+// Schema for database-dependent config (required fields)
 const mjConfigSchema = zod_1.z.object({
     dbHost: zod_1.z.string().default('localhost'),
     dbDatabase: zod_1.z.string(),
@@ -21,16 +22,51 @@ const mjConfigSchema = zod_1.z.object({
     cleanDisabled: zod_1.z.boolean().optional().default(true),
     mjRepoUrl: zod_1.z.string().url().catch(MJ_REPO_URL),
 });
-const parsedConfig = mjConfigSchema.safeParse(result?.config);
-if (!parsedConfig.success) {
-    console.error('Error parsing config file', JSON.stringify(parsedConfig.error.issues, null, 2));
-}
-exports.config = parsedConfig.success ? parsedConfig.data : undefined;
+// Schema for non-database commands (all fields optional)
+const mjConfigSchemaOptional = zod_1.z.object({
+    dbHost: zod_1.z.string().optional(),
+    dbDatabase: zod_1.z.string().optional(),
+    dbPort: zod_1.z.number({ coerce: true }).optional(),
+    codeGenLogin: zod_1.z.string().optional(),
+    codeGenPassword: zod_1.z.string().optional(),
+    migrationsLocation: zod_1.z.string().optional().default('filesystem:./migrations'),
+    dbTrustServerCertificate: zod_1.z.coerce.boolean().default(false),
+    coreSchema: zod_1.z.string().optional().default('__mj'),
+    cleanDisabled: zod_1.z.boolean().optional().default(true),
+    mjRepoUrl: zod_1.z.string().url().catch(MJ_REPO_URL),
+});
+// Don't validate at module load - let commands decide when they need validated config
+exports.config = result?.config;
+/**
+ * Get validated config for commands that require database connection.
+ * Throws error if config is invalid.
+ */
+const getValidatedConfig = () => {
+    const parsedConfig = mjConfigSchema.safeParse(result?.config);
+    if (!parsedConfig.success) {
+        throw new Error(`Invalid or missing mj.config.cjs file. Database commands require valid configuration.\n` +
+            `Missing fields: ${parsedConfig.error.issues.map(i => i.path.join('.')).join(', ')}`);
+    }
+    return parsedConfig.data;
+};
+exports.getValidatedConfig = getValidatedConfig;
+/**
+ * Get optional config for commands that don't require database connection.
+ * Returns undefined if no config exists, or partial config if it exists.
+ */
+const getOptionalConfig = () => {
+    const parsedConfig = mjConfigSchemaOptional.safeParse(result?.config);
+    return parsedConfig.success ? parsedConfig.data : undefined;
+};
+exports.getOptionalConfig = getOptionalConfig;
+/**
+ * Legacy function for backward compatibility with codegen.
+ * Validates and returns updated config.
+ * Returns undefined silently if config is invalid (command will handle the error).
+ */
 const updatedConfig = () => {
     const maybeConfig = mjConfigSchema.safeParse(explorer.search(process.cwd())?.config);
-    if (!maybeConfig.success) {
-        console.error('Error parsing config file', JSON.stringify(maybeConfig.error.issues, null, 2));
-    }
+    // Don't log errors here - let the calling command handle validation
     return maybeConfig.success ? maybeConfig.data : undefined;
 };
 exports.updatedConfig = updatedConfig;

package/oclif.manifest.json

@@ -305,6 +305,74 @@
         "export.js"
       ]
     },
+    "dbdoc:generate-queries": {
+      "aliases": [],
+      "args": {},
+      "description": "Generate sample SQL queries from existing analysis state (delegates to db-auto-doc generate-queries)",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --from-state ./output/run-1/state.json",
+        "<%= config.bin %> <%= command.id %> --from-state ./output/run-1/state.json --output-dir ./queries",
+        "<%= config.bin %> <%= command.id %> --from-state ./output/run-1/state.json --queries-per-table 10"
+      ],
+      "flags": {
+        "from-state": {
+          "description": "Path to existing state.json file from previous analysis",
+          "name": "from-state",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "output-dir": {
+          "description": "Output directory for generated queries",
+          "name": "output-dir",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "config": {
+          "char": "c",
+          "description": "Path to config file (for database connection and AI settings)",
+          "name": "config",
+          "default": "./config.json",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "queries-per-table": {
+          "description": "Number of queries to generate per table",
+          "name": "queries-per-table",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "max-execution-time": {
+          "description": "Maximum execution time for query validation (ms)",
+          "name": "max-execution-time",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "dbdoc:generate-queries",
+      "pluginAlias": "@memberjunction/cli",
+      "pluginName": "@memberjunction/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": false,
+      "relativePath": [
+        "dist",
+        "commands",
+        "dbdoc",
+        "generate-queries.js"
+      ]
+    },
     "dbdoc": {
       "aliases": [],
       "args": {},
@@ -1753,6 +1821,222 @@
         "run.js"
       ]
     },
+    "ai:audit:agent-run": {
+      "aliases": [],
+      "args": {
+        "runId": {
+          "description": "AI Agent Run ID to audit (UUID)",
+          "name": "runId",
+          "required": false
+        }
+      },
+      "description": "Audit and analyze AI agent execution runs for debugging and performance analysis",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> abc-123-def-456",
+        "<%= config.bin %> <%= command.id %> abc-123-def-456 --output=markdown",
+        "<%= config.bin %> <%= command.id %> abc-123-def-456 --step 3",
+        "<%= config.bin %> <%= command.id %> abc-123-def-456 --step 3 --detail full",
+        "<%= config.bin %> <%= command.id %> abc-123-def-456 --errors",
+        "<%= config.bin %> <%= command.id %> --list --agent \"Skip: Requirements Expert\"",
+        "<%= config.bin %> <%= command.id %> --list --status failed --days 7",
+        "<%= config.bin %> <%= command.id %> abc-123-def-456 --export full --file report.json"
+      ],
+      "flags": {
+        "output": {
+          "char": "o",
+          "description": "Output format",
+          "name": "output",
+          "default": "compact",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "compact",
+            "json",
+            "table",
+            "markdown"
+          ],
+          "type": "option"
+        },
+        "step": {
+          "char": "s",
+          "description": "Show details for specific step number (1-based index)",
+          "exclusive": [
+            "list",
+            "errors"
+          ],
+          "name": "step",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "detail": {
+          "char": "d",
+          "dependsOn": [
+            "step"
+          ],
+          "description": "Detail level for step output (default: standard)",
+          "name": "detail",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "minimal",
+            "standard",
+            "detailed",
+            "full"
+          ],
+          "type": "option"
+        },
+        "errors": {
+          "char": "e",
+          "description": "Show only error details and context",
+          "exclusive": [
+            "step",
+            "list"
+          ],
+          "name": "errors",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "list": {
+          "char": "l",
+          "description": "List recent agent runs",
+          "exclusive": [
+            "step",
+            "errors"
+          ],
+          "name": "list",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "agent": {
+          "char": "a",
+          "dependsOn": [
+            "list"
+          ],
+          "description": "Filter by agent name",
+          "name": "agent",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "status": {
+          "dependsOn": [
+            "list"
+          ],
+          "description": "Filter by run status",
+          "name": "status",
+          "default": "all",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "success",
+            "failed",
+            "running",
+            "all"
+          ],
+          "type": "option"
+        },
+        "days": {
+          "dependsOn": [
+            "list"
+          ],
+          "description": "Number of days to look back",
+          "name": "days",
+          "default": 7,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "limit": {
+          "dependsOn": [
+            "list"
+          ],
+          "description": "Maximum number of runs to return",
+          "name": "limit",
+          "default": 50,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "export": {
+          "dependsOn": [
+            "file"
+          ],
+          "description": "Export full data to file",
+          "name": "export",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "full",
+            "summary",
+            "steps"
+          ],
+          "type": "option"
+        },
+        "file": {
+          "char": "f",
+          "description": "Output file path for export",
+          "name": "file",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "max-tokens": {
+          "description": "Maximum tokens per field (0 = no limit)",
+          "name": "max-tokens",
+          "default": 5000,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "verbose": {
+          "char": "v",
+          "description": "Show detailed diagnostic information",
+          "name": "verbose",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "ai:audit:agent-run",
+      "pluginAlias": "@memberjunction/cli",
+      "pluginName": "@memberjunction/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": false,
+      "relativePath": [
+        "dist",
+        "commands",
+        "ai",
+        "audit",
+        "agent-run.js"
+      ]
+    },
+    "ai:audit": {
+      "aliases": [],
+      "args": {},
+      "description": "Analyze and audit AI agent runs, prompts, and actions for debugging and performance analysis",
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hidden": false,
+      "hiddenAliases": [],
+      "id": "ai:audit",
+      "pluginAlias": "@memberjunction/cli",
+      "pluginName": "@memberjunction/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": false,
+      "relativePath": [
+        "dist",
+        "commands",
+        "ai",
+        "audit",
+        "index.js"
+      ]
+    },
     "ai:prompts:list": {
       "aliases": [],
       "args": {},
@@ -1893,5 +2177,5 @@
       ]
     }
   },
-  "version": "2.118.0"
+  "version": "2.120.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/cli",
-  "version": "2.118.0",
+  "version": "2.120.0",
   "description": "MemberJunction command line tools",
   "keywords": [
     "oclif"
@@ -51,13 +51,13 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^5.0.1",
-    "@memberjunction/ai-cli": "2.118.0",
-    "@memberjunction/codegen-lib": "2.118.0",
-    "@memberjunction/core": "2.118.0",
-    "@memberjunction/db-auto-doc": "2.118.0",
-    "@memberjunction/metadata-sync": "2.118.0",
-    "@memberjunction/sqlserver-dataprovider": "2.118.0",
-    "@memberjunction/testing-cli": "2.118.0",
+    "@memberjunction/ai-cli": "2.120.0",
+    "@memberjunction/codegen-lib": "2.120.0",
+    "@memberjunction/core": "2.120.0",
+    "@memberjunction/db-auto-doc": "2.120.0",
+    "@memberjunction/metadata-sync": "2.120.0",
+    "@memberjunction/sqlserver-dataprovider": "2.120.0",
+    "@memberjunction/testing-cli": "2.120.0",
     "@oclif/core": "^3",
     "@oclif/plugin-help": "^6",
     "@oclif/plugin-version": "^2.0.17",