@memberjunction/cli 2.118.0 → 2.119.0

package/README.md

@@ -451,6 +451,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 +473,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 +513,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 +557,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 +569,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/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": {},
@@ -1893,5 +1961,5 @@
       ]
     }
   },
-  "version": "2.118.0"
+  "version": "2.119.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/cli",
-  "version": "2.118.0",
+  "version": "2.119.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.119.0",
+    "@memberjunction/codegen-lib": "2.119.0",
+    "@memberjunction/core": "2.119.0",
+    "@memberjunction/db-auto-doc": "2.119.0",
+    "@memberjunction/metadata-sync": "2.119.0",
+    "@memberjunction/sqlserver-dataprovider": "2.119.0",
+    "@memberjunction/testing-cli": "2.119.0",
     "@oclif/core": "^3",
     "@oclif/plugin-help": "^6",
     "@oclif/plugin-version": "^2.0.17",