@memberjunction/metadata-sync 5.40.2 → 5.42.0

package/dist/plugins/index.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Pluggable `mj sync` commands (plan §3/§5).
+ *
+ * These classes extend {@link BaseCLIPlugin} so they inherit `--format`,
+ * `--verbose`, `--no-banner`, the runtime advisory, and uniform result emission.
+ * They live behind the `@memberjunction/metadata-sync/plugins` subpath — NOT the
+ * package's main entry — so that loading them for oclif manifest generation or
+ * `mj usage` enumeration does NOT pull in the heavy sync engine. The engine is
+ * dynamic-imported inside `Execute()`, exactly as the original commands did, so
+ * the per-command lazy-loading contract is preserved.
+ *
+ * Stdio discipline (plan D2): no `ora`/`console` here. Progress goes through
+ * `this.Host.*`; rich human text is built with the engine's `FormattingService`
+ * and handed to `this.Host.Log` (which suppresses/redirects it in JSON mode).
+ */
+import { type Interfaces } from '@oclif/core';
+import { BaseCLIPlugin, type MJCLIResult, type PluginUsage } from '@memberjunction/cli-core';
+export declare class SyncPushPlugin extends BaseCLIPlugin {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        dir: Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
+        'dry-run': Interfaces.BooleanFlag<boolean>;
+        ci: Interfaces.BooleanFlag<boolean>;
+        'no-validate': Interfaces.BooleanFlag<boolean>;
+        'delete-db-only': Interfaces.BooleanFlag<boolean>;
+        'parallel-batch-size': Interfaces.OptionFlag<number, Interfaces.CustomOptions>;
+        include: Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
+        exclude: Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
+        incremental: Interfaces.BooleanFlag<boolean>;
+        'change-detail': Interfaces.BooleanFlag<boolean>;
+    };
+    static Usage: PluginUsage;
+    protected Execute(): Promise<MJCLIResult>;
+    /** Reproduces the original rich text summary (recap, change-detail file, box, status). */
+    private renderPushTextSummary;
+    private fail;
+    private cancelled;
+    /**
+     * Reset singletons + close the DB pool so the process can exit cleanly, then
+     * force-exit. Without this the pg.Pool/mssql pool — and any embedding ONNX
+     * worker threads — keep the event loop alive and the CLI hangs after a push.
+     */
+    protected Cleanup(result: MJCLIResult): Promise<void>;
+}
+export declare class SyncPullPlugin extends BaseCLIPlugin {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        entity: Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
+        filter: Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
+        'dry-run': Interfaces.BooleanFlag<boolean>;
+        'multi-file': Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
+        'no-validate': Interfaces.BooleanFlag<boolean>;
+        'update-existing': Interfaces.BooleanFlag<boolean>;
+        'create-new': Interfaces.BooleanFlag<boolean>;
+        'backup-before-update': Interfaces.BooleanFlag<boolean>;
+        'merge-strategy': Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
+        'backup-directory': Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
+        'preserve-fields': Interfaces.OptionFlag<string[], Interfaces.CustomOptions>;
+        'exclude-fields': Interfaces.OptionFlag<string[], Interfaces.CustomOptions>;
+        'target-dir': Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
+        incremental: Interfaces.BooleanFlag<boolean>;
+        since: Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
+    };
+    static Usage: PluginUsage;
+    protected Execute(): Promise<MJCLIResult>;
+    private findEntityDirectories;
+    private findAllEntityDirectoriesRecursive;
+    protected Cleanup(result: MJCLIResult): Promise<void>;
+}
+/** Tree-shaking / dynamic-load anchor — referenced by the CLI plugin loader. */
+export declare function LoadMetadataSyncPlugins(): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugins/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAGrD,OAAO,EAAE,aAAa,EAAE,KAAK,WAAW,EAAyB,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAqCpH,qBACa,cAAe,SAAQ,aAAa;IAC/C,MAAM,CAAC,WAAW,SAA6C;IAE/D,MAAM,CAAC,QAAQ,WAKb;IAEF,MAAM,CAAC,KAAK;;;;;;;;;;;MAyBV;IAEF,MAAM,CAAC,KAAK,EAAE,WAAW,CAgBvB;cAEc,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC;IAuK/C,0FAA0F;IAC1F,OAAO,CAAC,qBAAqB;IAqD7B,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,SAAS;IAKjB;;;;OAIG;cACa,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAU5D;AAMD,qBACa,cAAe,SAAQ,aAAa;IAC/C,MAAM,CAAC,WAAW,SAAgD;IAElE,MAAM,CAAC,QAAQ,WAIb;IAEF,MAAM,CAAC,KAAK;;;;;;;;;;;;;;;;MAgBV;IAEF,MAAM,CAAC,KAAK,EAAE,WAAW,CAevB;cAEc,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC;YAwJjC,qBAAqB;IAoBnC,OAAO,CAAC,iCAAiC;cAezB,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAU5D;AAED,gFAAgF;AAChF,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C"}

package/dist/plugins/index.js

@@ -0,0 +1,569 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+/**
+ * Pluggable `mj sync` commands (plan §3/§5).
+ *
+ * These classes extend {@link BaseCLIPlugin} so they inherit `--format`,
+ * `--verbose`, `--no-banner`, the runtime advisory, and uniform result emission.
+ * They live behind the `@memberjunction/metadata-sync/plugins` subpath — NOT the
+ * package's main entry — so that loading them for oclif manifest generation or
+ * `mj usage` enumeration does NOT pull in the heavy sync engine. The engine is
+ * dynamic-imported inside `Execute()`, exactly as the original commands did, so
+ * the per-command lazy-loading contract is preserved.
+ *
+ * Stdio discipline (plan D2): no `ora`/`console` here. Progress goes through
+ * `this.Host.*`; rich human text is built with the engine's `FormattingService`
+ * and handed to `this.Host.Log` (which suppresses/redirects it in JSON mode).
+ */
+import { Flags } from '@oclif/core';
+import { confirm, select } from '@inquirer/prompts';
+import { RegisterClass } from '@memberjunction/global';
+import { BaseCLIPlugin } from '@memberjunction/cli-core';
+import fs from 'fs';
+import path from 'path';
+import { writeFileSync } from 'fs';
+/** Shared loader for the heavy sync engine. Dynamic so the plugin module stays light. */
+async function loadEngine() {
+    return import('../index.js');
+}
+/**
+ * Flush stdout, then terminate. A buffered JSON result (e.g. piped to `jq`)
+ * would be truncated by a bare `process.exit()`, so we exit from the flush
+ * callback. An unref'd hard-exit timer guarantees termination even if the flush
+ * callback never fires or a lingering handle (mssql socket, embedding ONNX
+ * worker) keeps the event loop alive. Used by both push and pull cleanup so
+ * neither command can hang after emitting its result.
+ */
+function flushAndExit(code) {
+    const hardExit = setTimeout(() => process.exit(code), 2000);
+    hardExit.unref();
+    process.stdout.write('', () => process.exit(code));
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// mj sync push
+// ─────────────────────────────────────────────────────────────────────────────
+let SyncPushPlugin = class SyncPushPlugin extends BaseCLIPlugin {
+    static { this.description = 'Push local file changes to the database'; }
+    static { this.examples = [
+        `<%= config.bin %> <%= command.id %>`,
+        `<%= config.bin %> <%= command.id %> --dry-run`,
+        `<%= config.bin %> <%= command.id %> --dir="ai-prompts"`,
+        `<%= config.bin %> <%= command.id %> --ci --format=json`,
+    ]; }
+    static { this.flags = {
+        dir: Flags.string({ description: 'Specific entity directory to push' }),
+        'dry-run': Flags.boolean({ description: 'Show what would be pushed without actually pushing' }),
+        ci: Flags.boolean({ description: 'CI mode - no prompts, fail on issues' }),
+        'no-validate': Flags.boolean({ description: 'Skip validation before push' }),
+        'delete-db-only': Flags.boolean({
+            description: 'Delete database-only records that reference records being deleted (prevents FK errors)',
+            default: false,
+        }),
+        'parallel-batch-size': Flags.integer({
+            description: 'Number of records to process in parallel (default: 10)',
+            default: 10,
+            min: 1,
+            max: 50,
+        }),
+        include: Flags.string({ description: 'Only process these directories (comma-separated, supports patterns)' }),
+        exclude: Flags.string({ description: 'Skip these directories (comma-separated, supports patterns)' }),
+        incremental: Flags.boolean({
+            description: 'Skip unchanged files using stored checksums from last push',
+            default: false,
+        }),
+        'change-detail': Flags.boolean({
+            description: 'Write a detailed per-record change report (primary keys + field diffs) to a file',
+            default: false,
+        }),
+    }; }
+    static { this.Usage = {
+        domain: 'sync',
+        command: 'sync:push',
+        summary: 'Push local metadata files to the database (upsert).',
+        description: 'Reads entity directories under --dir and creates/updates matching records. Runs validation first unless --no-validate.',
+        flags: [
+            { name: '--dir', type: 'string', description: 'Entity directory to push' },
+            { name: '--dry-run', type: 'boolean', description: 'Report what would change without writing' },
+            { name: '--ci', type: 'boolean', description: 'No prompts; non-zero exit on error' },
+            { name: '--no-validate', type: 'boolean', description: 'Skip pre-push validation' },
+            { name: '--incremental', type: 'boolean', description: 'Skip unchanged files using stored checksums' },
+            { name: '--format', type: 'text|json|md', description: 'Output format (json for machine-readable result)' },
+        ],
+        examples: ['mj sync push --dir=ai-agents', 'mj sync push --ci --format=json'],
+        runtime: { class: 'variable', typicalSeconds: 20, note: 'scales with number of records in --dir' },
+    }; }
+    async Execute() {
+        const startTime = Date.now();
+        const flags = this.GetFlags();
+        const isText = this.Host.Format === 'text';
+        const nonInteractive = flags.ci || !isText;
+        const engine = await loadEngine();
+        const { PushService, ValidationService, FormattingService, loadMJConfig, loadSyncConfig, initializeProvider, getSyncEngine, getSystemUser, configManager, SyncStateManager, } = engine;
+        const errors = [];
+        const warnings = [];
+        try {
+            this.Host.StartStep('Loading configuration');
+            const mjConfig = loadMJConfig();
+            if (!mjConfig) {
+                this.Host.FailStep('Loading configuration', 'No mj.config.cjs found');
+                return this.fail(startTime, [{ message: 'No mj.config.cjs found in current directory or parent directories' }]);
+            }
+            const baseDir = configManager.getOriginalCwd();
+            const syncConfigDir = flags.dir ? path.resolve(baseDir, flags.dir) : baseDir;
+            await loadSyncConfig(syncConfigDir);
+            await initializeProvider(mjConfig);
+            await getSyncEngine(getSystemUser());
+            this.Host.SucceedStep('Configuration and metadata loaded');
+            const includeFilter = flags.include ? flags.include.split(',').map((s) => s.trim()) : undefined;
+            const excludeFilter = flags.exclude ? flags.exclude.split(',').map((s) => s.trim()) : undefined;
+            const formatter = new FormattingService();
+            // ── Validation ────────────────────────────────────────────────────────────
+            if (!flags['no-validate']) {
+                this.Host.StartStep('Validating metadata');
+                const validator = new ValidationService({ verbose: this.Host.Verbose, include: includeFilter, exclude: excludeFilter });
+                const targetDir = flags.dir ? path.resolve(baseDir, flags.dir) : baseDir;
+                const validationResult = await validator.validateDirectory(targetDir);
+                if (!validationResult.isValid || validationResult.warnings.length > 0) {
+                    this.Host.FailStep('Validation reported issues');
+                    if (isText)
+                        this.Host.Log('\n' + formatter.formatValidationResult(validationResult, this.Host.Verbose));
+                    if (!validationResult.isValid) {
+                        if (nonInteractive) {
+                            return this.fail(startTime, [{ context: 'validation', message: 'Validation failed. Cannot proceed with push.' }]);
+                        }
+                        const shouldContinue = await confirm({
+                            message: 'Validation failed with errors. Do you want to continue anyway?',
+                            default: false,
+                        });
+                        if (!shouldContinue) {
+                            // Clean cancel (exit 0) — matches the original interactive behavior.
+                            return this.cancelled(startTime, 'Push cancelled due to validation errors.');
+                        }
+                    }
+                }
+                else {
+                    this.Host.SucceedStep('Validation passed');
+                }
+            }
+            // ── Push ────────────────────────────────────────────────────────────────��─
+            const pushService = new PushService(await getSyncEngine(getSystemUser()), getSystemUser());
+            if (flags.incremental) {
+                const stateDir = flags.dir ? path.resolve(baseDir, flags.dir) : baseDir;
+                const stateManager = new SyncStateManager(stateDir);
+                await stateManager.load();
+                pushService.setStateManager(stateManager);
+            }
+            const result = await pushService.push({
+                dir: flags.dir,
+                dryRun: flags['dry-run'],
+                verbose: this.Host.Verbose,
+                noValidate: flags['no-validate'],
+                deleteDbOnly: flags['delete-db-only'],
+                parallelBatchSize: flags['parallel-batch-size'],
+                include: includeFilter,
+                exclude: excludeFilter,
+                incremental: flags.incremental,
+            }, {
+                onProgress: (message) => this.Host.StartStep(message),
+                onSuccess: (message) => this.Host.SucceedStep(message),
+                // onError is multi-line HUMAN logging — route to the host, do NOT treat
+                // each line as a discrete error. Structured per-record failures arrive
+                // via onRecordError (below), so errors[] stays clean (plan §1a/§6/D6).
+                onError: (message) => {
+                    if (message.includes('Rolling back database') || message.includes('rolled back successfully')) {
+                        warnings.push(message);
+                        this.Host.Log(message, 'warn');
+                    }
+                    else {
+                        this.Host.Log(message, 'error');
+                    }
+                },
+                onRecordError: (d) => {
+                    const context = d.path ? `${d.path}${d.entityName ? ` [${d.entityName}]` : ''}` : d.entityName || undefined;
+                    const message = d.primaryKey ? `${d.message} (pk: ${d.primaryKey})` : d.message;
+                    errors.push({ context, message });
+                },
+                onWarn: (message) => {
+                    warnings.push(message);
+                    this.Host.Log(message, 'warn');
+                },
+                onLog: (message) => this.Host.Log(message),
+                onConfirm: async (message) => (nonInteractive ? true : confirm({ message })),
+            });
+            const endTime = Date.now();
+            for (const w of result.warnings)
+                if (!warnings.includes(w))
+                    warnings.push(w);
+            // Recovery decision: with non-fatal errors, the original CLI asked whether to
+            // keep the successfully-committed changes. Preserve that for interactive text
+            // mode. CI / non-interactive keeps the failure (no prompt possible).
+            let success = result.errors === 0 && errors.length === 0;
+            if (!success && result.errors > 0 && !flags.ci && isText) {
+                const commit = await confirm({
+                    message: 'Push completed with errors. Do you want to commit the successful changes?',
+                    default: false,
+                });
+                if (commit)
+                    success = true;
+                else
+                    warnings.push('Push cancelled due to errors.');
+            }
+            if (isText) {
+                this.renderPushTextSummary(formatter, result, flags['change-detail'], startTime, endTime);
+            }
+            return {
+                success,
+                command: 'sync:push',
+                durationSeconds: (endTime - startTime) / 1000,
+                data: {
+                    created: result.created,
+                    updated: result.updated,
+                    unchanged: result.unchanged,
+                    deleted: result.deleted ?? 0,
+                    skipped: result.skipped ?? 0,
+                    deferred: result.deferred ?? 0,
+                    // The raw engine error COUNT is always present, even when fail-fast threw
+                    // before every failing record could be enumerated into errors[].
+                    errorCount: result.errors,
+                    dryRun: !!flags['dry-run'],
+                    sqlLogPath: result.sqlLogPath,
+                },
+                errors,
+                warnings,
+            };
+        }
+        catch (error) {
+            // Infrastructure failures (config load, DB connect, etc.) — surface them
+            // as a structured result so JSON consumers always get an output, and so
+            // Cleanup() still runs to close the pool. If a per-record failure already
+            // populated errors[] (fail-fast throws AFTER onRecordError fires), don't
+            // duplicate it with the rethrown wrapper message.
+            const message = error instanceof Error ? error.message : String(error);
+            this.Host.FailStep('Push failed', message);
+            if (errors.length === 0)
+                errors.push({ message });
+            return { success: false, command: 'sync:push', durationSeconds: (Date.now() - startTime) / 1000, errors, warnings };
+        }
+    }
+    /** Reproduces the original rich text summary (recap, change-detail file, box, status). */
+    renderPushTextSummary(formatter, result, changeDetail, startTime, endTime) {
+        const recap = formatter.formatChangesRecap(result.changeLog);
+        if (recap)
+            this.Host.Log('\n' + recap);
+        if (changeDetail && result.changeLog.length > 0) {
+            const stamp = new Date(endTime).toISOString().replace(/[:.]/g, '-');
+            const reportDir = result.sqlLogPath ? path.dirname(result.sqlLogPath) : process.cwd();
+            const reportPath = path.join(reportDir, `MetadataSync_Changes_${stamp}.log`);
+            try {
+                writeFileSync(reportPath, formatter.formatChangesReport(result.changeLog, new Date(endTime).toISOString()));
+                this.Host.Log(`\n📄 Detailed change report: ${path.relative(process.cwd(), reportPath)}`);
+            }
+            catch (writeErr) {
+                this.Host.Log(`\n⚠️  Could not write change report: ${writeErr instanceof Error ? writeErr.message : String(writeErr)}`, 'warn');
+            }
+        }
+        const changed = result.created > 0 || result.updated > 0 || (result.deleted || 0) > 0 || result.errors > 0;
+        if (changed || this.Host.Verbose) {
+            this.Host.Log('\n' +
+                formatter.formatSyncSummary('push', {
+                    created: result.created,
+                    updated: result.updated,
+                    unchanged: result.unchanged,
+                    deleted: result.deleted || 0,
+                    skipped: result.skipped || 0,
+                    deferred: result.deferred || 0,
+                    errors: result.errors,
+                    duration: endTime - startTime,
+                }));
+        }
+        if (result.warnings.length > 0) {
+            this.Host.Log(`\n⚠️  ${result.warnings.length} warning${result.warnings.length > 1 ? 's' : ''} during push`, 'warn');
+            if (this.Host.Verbose)
+                result.warnings.forEach((w) => this.Host.Log(`   - ${w}`, 'warn'));
+        }
+        const extras = changed || this.Host.Verbose ? '' : ` · no changes · ${formatter.formatDuration(endTime - startTime)}`;
+        if (result.errors === 0) {
+            this.Host.Log(`\n✓ Push completed successfully${extras}`);
+        }
+        else {
+            this.Host.Log('\n⚠️  Push completed with errors', 'warn');
+        }
+        if (result.sqlLogPath)
+            this.Host.Log(`\n📄 SQL log saved to: ${path.relative(process.cwd(), result.sqlLogPath)}`);
+    }
+    fail(startTime, errors) {
+        return { success: false, command: 'sync:push', durationSeconds: (Date.now() - startTime) / 1000, errors };
+    }
+    cancelled(startTime, message) {
+        if (this.Host.Format === 'text')
+            this.Host.Log(`\n⚠️  ${message}`, 'warn');
+        return { success: true, command: 'sync:push', durationSeconds: (Date.now() - startTime) / 1000, warnings: [message] };
+    }
+    /**
+     * Reset singletons + close the DB pool so the process can exit cleanly, then
+     * force-exit. Without this the pg.Pool/mssql pool — and any embedding ONNX
+     * worker threads — keep the event loop alive and the CLI hangs after a push.
+     */
+    async Cleanup(result) {
+        try {
+            const { resetSyncEngine, cleanupProvider } = await loadEngine();
+            resetSyncEngine();
+            await cleanupProvider();
+        }
+        catch {
+            // best-effort
+        }
+        flushAndExit(result.success ? 0 : 1);
+    }
+};
+SyncPushPlugin = __decorate([
+    RegisterClass(BaseCLIPlugin, 'sync:push')
+], SyncPushPlugin);
+export { SyncPushPlugin };
+// ─────────────────────────────────────────────────────────────────────────────
+// mj sync pull
+// ─────────────────────────────────────────────────────────────────────────────
+let SyncPullPlugin = class SyncPullPlugin extends BaseCLIPlugin {
+    static { this.description = 'Pull metadata from database to local files'; }
+    static { this.examples = [
+        `<%= config.bin %> <%= command.id %> --entity="MJ: AI Prompts"`,
+        `<%= config.bin %> <%= command.id %> --entity="MJ: AI Agents" --merge-strategy=overwrite`,
+        `<%= config.bin %> <%= command.id %> --entity="Templates" --dry-run --verbose`,
+    ]; }
+    static { this.flags = {
+        entity: Flags.string({ description: 'Entity name to pull', required: true }),
+        filter: Flags.string({ description: 'Additional filter for pulling specific records' }),
+        'dry-run': Flags.boolean({ description: 'Show what would be pulled without actually pulling' }),
+        'multi-file': Flags.string({ description: 'Create a single file with multiple records (provide filename)' }),
+        'no-validate': Flags.boolean({ description: 'Skip validation before pull' }),
+        'update-existing': Flags.boolean({ description: 'Update existing records during pull', default: true }),
+        'create-new': Flags.boolean({ description: 'Create new files for records not found locally', default: true }),
+        'backup-before-update': Flags.boolean({ description: 'Create backups before updating files', default: true }),
+        'merge-strategy': Flags.string({ description: 'Merge strategy for updates', options: ['merge', 'overwrite', 'skip'], default: 'merge' }),
+        'backup-directory': Flags.string({ description: 'Custom backup directory (default: .backups)' }),
+        'preserve-fields': Flags.string({ description: 'Comma-separated list of fields to preserve during updates', multiple: true }),
+        'exclude-fields': Flags.string({ description: 'Comma-separated list of fields to exclude from pull', multiple: true }),
+        'target-dir': Flags.string({ description: 'Specific target directory (overrides auto-discovery)' }),
+        incremental: Flags.boolean({ description: 'Only pull records updated since last successful pull', default: false }),
+        since: Flags.string({ description: 'Only pull records updated after this ISO 8601 timestamp' }),
+    }; }
+    static { this.Usage = {
+        domain: 'sync',
+        command: 'sync:pull',
+        summary: 'Pull database records into local metadata files.',
+        description: 'Writes records of --entity into the matching entity directory, creating or updating files per the merge strategy.',
+        flags: [
+            { name: '--entity', type: 'string', description: 'Entity name to pull (required)' },
+            { name: '--filter', type: 'string', description: 'Extra SQL filter for which records to pull' },
+            { name: '--merge-strategy', type: 'merge|overwrite|skip', description: 'How to reconcile existing files' },
+            { name: '--dry-run', type: 'boolean', description: 'Report what would be pulled without writing' },
+            { name: '--format', type: 'text|json|md', description: 'Output format (json for machine-readable result)' },
+        ],
+        examples: ['mj sync pull --entity="MJ: AI Prompts"', 'mj sync pull --entity="Actions" --format=json'],
+        runtime: { class: 'variable', typicalSeconds: 15, note: 'scales with number of records matched for --entity' },
+    }; }
+    async Execute() {
+        const startTime = Date.now();
+        const flags = this.GetFlags();
+        const isText = this.Host.Format === 'text';
+        const nonInteractive = !isText;
+        const engine = await loadEngine();
+        const { PullService, ValidationService, FormattingService, loadMJConfig, initializeProvider, getSyncEngine, getSystemUser, configManager, loadEntityConfig, FileBackupManager, SyncStateManager, } = engine;
+        const errors = [];
+        const warnings = [];
+        let backupManager = null;
+        try {
+            this.Host.StartStep('Loading configuration');
+            const mjConfig = loadMJConfig();
+            if (!mjConfig) {
+                this.Host.FailStep('Loading configuration', 'No mj.config.cjs found');
+                return { success: false, command: 'sync:pull', durationSeconds: (Date.now() - startTime) / 1000, errors: [{ message: 'No mj.config.cjs found in current directory or parent directories' }] };
+            }
+            await initializeProvider(mjConfig);
+            const syncEngine = await getSyncEngine(getSystemUser());
+            this.Host.SucceedStep('Configuration and metadata loaded');
+            const entityDirectories = await this.findEntityDirectories(flags.entity, configManager, loadEntityConfig, warnings);
+            if (entityDirectories.length === 0) {
+                return { success: false, command: 'sync:pull', durationSeconds: (Date.now() - startTime) / 1000, errors: [{ context: flags.entity, message: `No directories found for entity "${flags.entity}". Ensure its .mj-sync.json config exists.` }] };
+            }
+            let targetDir = flags['target-dir'];
+            if (!targetDir) {
+                if (entityDirectories.length === 1) {
+                    targetDir = entityDirectories[0];
+                }
+                else if (nonInteractive) {
+                    return { success: false, command: 'sync:pull', durationSeconds: (Date.now() - startTime) / 1000, errors: [{ context: flags.entity, message: `Multiple directories found for "${flags.entity}"; pass --target-dir to choose one in non-interactive mode.` }] };
+                }
+                else {
+                    targetDir = await select({
+                        message: `Multiple directories found for entity "${flags.entity}". Which one to use?`,
+                        choices: entityDirectories.map((dir) => ({ name: dir, value: dir })),
+                    });
+                }
+            }
+            const formatter = new FormattingService();
+            if (!flags['no-validate']) {
+                this.Host.StartStep('Validating target directory');
+                const validator = new ValidationService({ verbose: this.Host.Verbose });
+                const validationResult = await validator.validateDirectory(targetDir);
+                if (!validationResult.isValid || validationResult.warnings.length > 0) {
+                    this.Host.FailStep('Validation reported issues');
+                    if (isText)
+                        this.Host.Log('\n' + formatter.formatValidationResult(validationResult, this.Host.Verbose));
+                    if (!validationResult.isValid) {
+                        if (nonInteractive) {
+                            return { success: false, command: 'sync:pull', durationSeconds: (Date.now() - startTime) / 1000, errors: [{ context: 'validation', message: 'Validation failed. Cannot proceed with pull.' }] };
+                        }
+                        const shouldContinue = await confirm({ message: 'Validation failed with errors. Continue anyway?', default: false });
+                        if (!shouldContinue) {
+                            if (isText)
+                                this.Host.Log('\n⚠️  Pull cancelled due to validation errors.', 'warn');
+                            return { success: true, command: 'sync:pull', durationSeconds: (Date.now() - startTime) / 1000, warnings: ['Pull cancelled due to validation errors.'] };
+                        }
+                    }
+                }
+                else {
+                    this.Host.SucceedStep('Validation passed');
+                }
+            }
+            if (flags['backup-before-update']) {
+                backupManager = new FileBackupManager();
+                await backupManager.initialize();
+            }
+            const pullService = new PullService(syncEngine, getSystemUser());
+            if (flags.incremental || flags.since) {
+                const stateManager = new SyncStateManager(targetDir);
+                await stateManager.load();
+                pullService.setStateManager(stateManager);
+            }
+            // Only the fields PullService.pull() actually reads are forwarded; the
+            // backup/merge/preserve/exclude flags it ignores are kept for help/CLI
+            // compatibility but were no-ops in the original (passed via `any`).
+            const pullOptions = { entity: flags.entity, targetDir, dryRun: flags['dry-run'], verbose: this.Host.Verbose, noValidate: flags['no-validate'] };
+            if (flags.filter !== undefined)
+                pullOptions.filter = flags.filter;
+            if (flags['multi-file'] !== undefined)
+                pullOptions.multiFile = flags['multi-file'];
+            if (flags['update-existing'] !== undefined)
+                pullOptions.updateExistingRecords = flags['update-existing'];
+            if (flags['create-new'] !== undefined)
+                pullOptions.createNewFileIfNotFound = flags['create-new'];
+            if (flags.incremental)
+                pullOptions.incremental = flags.incremental;
+            if (flags.since !== undefined)
+                pullOptions.since = flags.since;
+            const result = await pullService.pull(pullOptions, {
+                onProgress: (message) => this.Host.StartStep(message),
+                onSuccess: (message) => this.Host.SucceedStep(message),
+                onError: (message) => {
+                    errors.push({ message });
+                    this.Host.FailStep(message);
+                },
+                onWarn: (message) => {
+                    warnings.push(message);
+                    this.Host.Log(message, 'warn');
+                },
+                onLog: (message) => this.Host.Log(message),
+            });
+            if (backupManager && !flags['dry-run']) {
+                await backupManager.cleanup();
+            }
+            if (!flags['dry-run']) {
+                try {
+                    await pullService.cleanupBackupFiles();
+                }
+                catch (cleanupError) {
+                    warnings.push(`Failed to cleanup persistent backup files: ${cleanupError}`);
+                }
+            }
+            if (isText && !flags['dry-run'])
+                this.Host.Log('\n✅ Pull completed successfully');
+            return {
+                success: errors.length === 0,
+                command: 'sync:pull',
+                durationSeconds: (Date.now() - startTime) / 1000,
+                data: {
+                    entity: flags.entity,
+                    targetDir: result.targetDir,
+                    processed: result.processed,
+                    created: result.created,
+                    updated: result.updated,
+                    skipped: result.skipped,
+                    dryRun: !!flags['dry-run'],
+                },
+                errors,
+                warnings,
+            };
+        }
+        catch (error) {
+            if (backupManager) {
+                try {
+                    await backupManager.rollback();
+                }
+                catch (rollbackError) {
+                    warnings.push(`Failed to rollback backup files: ${rollbackError}`);
+                }
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            this.Host.FailStep('Pull failed', message);
+            errors.push({ context: flags.entity, message });
+            return { success: false, command: 'sync:pull', durationSeconds: (Date.now() - startTime) / 1000, errors, warnings };
+        }
+    }
+    async findEntityDirectories(entityName, configMgr, loadConfig, warnings) {
+        const workingDir = configMgr.getOriginalCwd();
+        const allDirs = this.findAllEntityDirectoriesRecursive(workingDir);
+        const entityDirs = [];
+        for (const dir of allDirs) {
+            try {
+                const config = await loadConfig(dir);
+                if (config && config.entity === entityName)
+                    entityDirs.push(dir);
+            }
+            catch (error) {
+                warnings.push(`Skipping directory ${dir}: invalid configuration (${error})`);
+            }
+        }
+        return entityDirs;
+    }
+    findAllEntityDirectoriesRecursive(dir) {
+        const directories = [];
+        try {
+            if (fs.existsSync(path.join(dir, '.mj-sync.json')))
+                directories.push(dir);
+            for (const item of fs.readdirSync(dir, { withFileTypes: true })) {
+                if (item.isDirectory() && !item.name.startsWith('.')) {
+                    directories.push(...this.findAllEntityDirectoriesRecursive(path.join(dir, item.name)));
+                }
+            }
+        }
+        catch {
+            // Skip directories we can't read
+        }
+        return directories;
+    }
+    async Cleanup(result) {
+        try {
+            const { resetSyncEngine, cleanupProvider } = await loadEngine();
+            resetSyncEngine();
+            await cleanupProvider();
+        }
+        catch {
+            // best-effort
+        }
+        flushAndExit(result.success ? 0 : 1);
+    }
+};
+SyncPullPlugin = __decorate([
+    RegisterClass(BaseCLIPlugin, 'sync:pull')
+], SyncPullPlugin);
+export { SyncPullPlugin };
+/** Tree-shaking / dynamic-load anchor — referenced by the CLI plugin loader. */
+export function LoadMetadataSyncPlugins() {
+    // no-op; importing this module triggers the @RegisterClass decorators above.
+}
+//# sourceMappingURL=index.js.map