ado-sync 0.1.65 → 0.1.68

package/dist/cli.js

@@ -55,7 +55,9 @@ const readline = __importStar(require("readline"));
 const package_json_1 = __importDefault(require("../package.json"));
 const summarizer_1 = require("./ai/summarizer");
 const client_1 = require("./azure/client");
+const cli_diagnostics_1 = require("./cli-diagnostics");
 const config_1 = require("./config");
+const id_markers_1 = require("./id-markers");
 const engine_1 = require("./sync/engine");
 const generate_1 = require("./sync/generate");
 const manifest_1 = require("./sync/manifest");
@@ -69,6 +71,17 @@ program
 // Global options
 program.option('-c, --config <path>', 'Path to config file (default: ado-sync.json)');
 program.option('--output <format>', 'Output format: text (default) or json');
+program.option('--pat-override <token>', 'Override auth.token for this invocation (not persisted to config)');
+program.option('--org-override <url>', 'Override orgUrl for this invocation (not persisted to config)');
+function loadConfigWithOverrides(configPath) {
+    const config = (0, config_1.loadConfig)(configPath);
+    const globalOpts = program.opts();
+    if (globalOpts.patOverride)
+        config.auth.token = globalOpts.patOverride;
+    if (globalOpts.orgOverride)
+        config.orgUrl = globalOpts.orgOverride;
+    return config;
+}
 // ─── Error formatting (L) ─────────────────────────────────────────────────────
 function toError(err) {
     if (err instanceof Error)
@@ -101,6 +114,17 @@ function handleError(err) {
 function collect(value, previous) {
     return [...previous, value];
 }
+function normalizeSourceFilesForCli(sourceFiles, configDir) {
+    if (!sourceFiles?.length)
+        return undefined;
+    return sourceFiles.map((filePath) => path.normalize(path.resolve(configDir, filePath)));
+}
+function printDiagnosticItems(items) {
+    console.log(chalk_1.default.bold('Diagnostics:'));
+    for (const item of items) {
+        console.log(chalk_1.default.dim(`  ${item.label}: ${item.value}`));
+    }
+}
 // ─── AI summary helper ────────────────────────────────────────────────────────
 /**
  * Build AiSummaryOpts from parsed CLI opts, falling back to config file values.
@@ -243,12 +267,97 @@ async function runInitWizard(isYaml) {
     }
     return JSON.stringify(cfg, null, 2) + '\n';
 }
+// ─── config ───────────────────────────────────────────────────────────────────
+const configCmd = program
+    .command('config')
+    .description('Configuration inspection and management');
+configCmd
+    .command('show')
+    .description('Display the fully resolved configuration (after parent merge, env vars, and overrides)')
+    .option('--config-override <path=value>', 'Override a config value (repeatable)', collect, [])
+    .action(async (opts) => {
+    const globalOpts = program.opts();
+    try {
+        const configPath = (0, config_1.resolveConfigPath)(globalOpts.config);
+        const config = loadConfigWithOverrides(configPath);
+        if (opts.configOverride?.length)
+            (0, config_1.applyOverrides)(config, opts.configOverride);
+        const redacted = { ...config, auth: { ...config.auth, token: config.auth?.token ? '***' : undefined } };
+        process.stdout.write(JSON.stringify(redacted, null, 2) + '\n');
+    }
+    catch (err) {
+        handleError(err);
+    }
+});
+// ─── extensions ───────────────────────────────────────────────────────────────
+const extCmd = program
+    .command('extensions')
+    .description('Manage ado-sync extensions');
+extCmd
+    .command('list')
+    .description('List registered extensions from config')
+    .action(async () => {
+    const globalOpts = program.opts();
+    try {
+        const configPath = (0, config_1.resolveConfigPath)(globalOpts.config);
+        const config = loadConfigWithOverrides(configPath);
+        const extensions = config.extensions ?? [];
+        if (extensions.length === 0) {
+            console.log(chalk_1.default.dim('No extensions configured.'));
+            return;
+        }
+        for (const ext of extensions) {
+            console.log(`${chalk_1.default.bold(ext.name)} ${chalk_1.default.dim(`(${ext.type})`)} — ${ext.package}`);
+            if (ext.filePatterns?.length) {
+                console.log(chalk_1.default.dim(`  patterns: ${ext.filePatterns.join(', ')}`));
+            }
+        }
+    }
+    catch (err) {
+        handleError(err);
+    }
+});
+extCmd
+    .command('validate')
+    .description('Validate extension compatibility and loading')
+    .action(async () => {
+    const globalOpts = program.opts();
+    try {
+        const configPath = (0, config_1.resolveConfigPath)(globalOpts.config);
+        const config = loadConfigWithOverrides(configPath);
+        const configDir = path.dirname(configPath);
+        const extensions = config.extensions ?? [];
+        if (extensions.length === 0) {
+            console.log(chalk_1.default.dim('No extensions configured.'));
+            return;
+        }
+        const { loadExtensions, validateExtensions } = await Promise.resolve().then(() => __importStar(require('./extensions')));
+        const loaded = await loadExtensions(extensions, configDir);
+        const errors = validateExtensions(loaded, package_json_1.default.version);
+        if (errors.length) {
+            for (const err of errors)
+                console.log(chalk_1.default.red(`  ✗ ${err}`));
+            process.exit(1);
+        }
+        for (const ext of loaded) {
+            console.log(chalk_1.default.green(`  ✓ ${ext.config.name}`) + chalk_1.default.dim(` v${ext.manifest.version} (${ext.manifest.type})`));
+        }
+    }
+    catch (err) {
+        handleError(err);
+    }
+});
 // ─── push ─────────────────────────────────────────────────────────────────────
 program
     .command('push')
     .description('Push local test specs to Azure DevOps (create or update test cases)')
     .option('--dry-run', 'Show what would change without making any modifications')
+    .option('--create-only', 'Only create test cases for unlinked local specs; skip linked items and removed-case detection')
+    .option('--link-only', 'Only restore local IDs by linking unlinked specs to uniquely matching existing test cases in the current scope')
+    .option('--update-only', 'Only update linked test cases; skip unlinked specs and removed-case detection')
     .option('--tags <expression>', 'Only sync scenarios matching this tag expression (e.g. "@smoke and not @wip")')
+    .option('--source-file <path>', 'Restrict the operation to a specific local file (repeatable)', collect, [])
+    .option('--include <pattern>', 'Restrict the operation to files matching a glob pattern relative to config dir (repeatable)', collect, [])
     .option('--config-override <path=value>', 'Override a config value (repeatable, e.g. --config-override sync.tagPrefix=mytag)', collect, [])
     .option('--ai-provider <provider>', 'AI provider: local (node-llama-cpp), heuristic, ollama, docker, openai, anthropic, huggingface, bedrock, azureai, none (disable)')
     .option('--ai-model <model>', 'local: GGUF path; ollama/docker: model tag; openai/anthropic/huggingface/bedrock/azureai: model name or id')
@@ -260,9 +369,10 @@ program
     const globalOpts = program.opts();
     try {
         const configPath = (0, config_1.resolveConfigPath)(globalOpts.config);
-        const config = (0, config_1.loadConfig)(configPath);
+        const config = loadConfigWithOverrides(configPath);
         if (opts.configOverride?.length)
             (0, config_1.applyOverrides)(config, opts.configOverride);
+        (0, engine_1.validatePushModeOptions)(opts);
         const configDir = path.dirname(configPath);
         console.log(chalk_1.default.bold('ado-sync push'));
         console.log(chalk_1.default.dim(`Config:  ${configPath}`));
@@ -270,8 +380,18 @@ program
         console.log(chalk_1.default.dim(`Plan:    ${config.testPlan.id}`));
         if (opts.dryRun)
             console.log(chalk_1.default.yellow('Dry run — no changes will be made'));
+        if (opts.createOnly)
+            console.log(chalk_1.default.dim('Mode:    create-only'));
+        if (opts.linkOnly)
+            console.log(chalk_1.default.dim('Mode:    link-only'));
+        if (opts.updateOnly)
+            console.log(chalk_1.default.dim('Mode:    update-only'));
         if (opts.tags)
             console.log(chalk_1.default.dim(`Tags:    ${opts.tags}`));
+        if (opts.sourceFile?.length)
+            console.log(chalk_1.default.dim(`Files:   ${opts.sourceFile.join(', ')}`));
+        if (opts.include?.length)
+            console.log(chalk_1.default.dim(`Include: ${opts.include.join(', ')}`));
         if (opts.configOverride?.length)
             console.log(chalk_1.default.dim(`Overrides: ${opts.configOverride.join(', ')}`));
         console.log('');
@@ -280,7 +400,7 @@ program
         const outputFormat = program.opts().output;
         const onProgress = outputFormat === 'json' ? undefined : createProgressCallback(isTTY);
         const onAiProgress = outputFormat === 'json' ? undefined : createAiProgressCallback(isTTY);
-        const results = await (0, engine_1.push)(config, configDir, { dryRun: opts.dryRun, tags: opts.tags, onProgress, onAiProgress, aiSummary });
+        const results = await (0, engine_1.push)(config, configDir, { dryRun: opts.dryRun, createOnly: opts.createOnly, linkOnly: opts.linkOnly, updateOnly: opts.updateOnly, tags: opts.tags, sourceFiles: opts.sourceFile, includePatterns: opts.include?.length ? opts.include : undefined, onProgress, onAiProgress, aiSummary });
         if (isTTY && outputFormat !== 'json')
             clearProgressLine();
         printResults(results, config.toolSettings?.outputLevel, outputFormat);
@@ -295,12 +415,14 @@ program
     .description('Pull updates from Azure DevOps into local spec files')
     .option('--dry-run', 'Show what would change without modifying local files')
     .option('--tags <expression>', 'Only sync scenarios matching this tag expression (e.g. "@smoke and not @wip")')
+    .option('--source-file <path>', 'Restrict the operation to a specific local file (repeatable)', collect, [])
+    .option('--include <pattern>', 'Restrict the operation to files matching a glob pattern relative to config dir (repeatable)', collect, [])
     .option('--config-override <path=value>', 'Override a config value (repeatable)', collect, [])
     .action(async (opts) => {
     const globalOpts = program.opts();
     try {
         const configPath = (0, config_1.resolveConfigPath)(globalOpts.config);
-        const config = (0, config_1.loadConfig)(configPath);
+        const config = loadConfigWithOverrides(configPath);
         if (opts.configOverride?.length)
             (0, config_1.applyOverrides)(config, opts.configOverride);
         const configDir = path.dirname(configPath);
@@ -310,11 +432,15 @@ program
             console.log(chalk_1.default.yellow('Dry run — no changes will be made'));
         if (opts.tags)
             console.log(chalk_1.default.dim(`Tags:    ${opts.tags}`));
+        if (opts.sourceFile?.length)
+            console.log(chalk_1.default.dim(`Files:   ${opts.sourceFile.join(', ')}`));
+        if (opts.include?.length)
+            console.log(chalk_1.default.dim(`Include: ${opts.include.join(', ')}`));
         console.log('');
         const isTTY = process.stdout.isTTY ?? false;
         const outputFormat = program.opts().output;
         const onProgress = outputFormat === 'json' ? undefined : createProgressCallback(isTTY);
-        const results = await (0, engine_1.pull)(config, configDir, { dryRun: opts.dryRun, tags: opts.tags, onProgress });
+        const results = await (0, engine_1.pull)(config, configDir, { dryRun: opts.dryRun, tags: opts.tags, sourceFiles: opts.sourceFile, includePatterns: opts.include?.length ? opts.include : undefined, onProgress });
         if (isTTY && outputFormat !== 'json')
             clearProgressLine();
         printResults(results, config.toolSettings?.outputLevel, outputFormat);
@@ -328,6 +454,8 @@ program
     .command('status')
     .description('Show diff between local specs and Azure DevOps without making changes')
     .option('--tags <expression>', 'Only check scenarios matching this tag expression')
+    .option('--source-file <path>', 'Restrict the operation to a specific local file (repeatable)', collect, [])
+    .option('--include <pattern>', 'Restrict the operation to files matching a glob pattern relative to config dir (repeatable)', collect, [])
     .option('--config-override <path=value>', 'Override a config value (repeatable)', collect, [])
     .option('--ai-provider <provider>', 'AI provider: local (node-llama-cpp), heuristic, ollama, docker, openai, anthropic, huggingface, bedrock, azureai, none (disable)')
     .option('--ai-model <model>', 'local: GGUF path; ollama/docker: model tag; openai/anthropic/huggingface/bedrock/azureai: model name or id')
@@ -339,7 +467,7 @@ program
     const globalOpts = program.opts();
     try {
         const configPath = (0, config_1.resolveConfigPath)(globalOpts.config);
-        const config = (0, config_1.loadConfig)(configPath);
+        const config = loadConfigWithOverrides(configPath);
         if (opts.configOverride?.length)
             (0, config_1.applyOverrides)(config, opts.configOverride);
         const configDir = path.dirname(configPath);
@@ -347,13 +475,17 @@ program
         console.log(chalk_1.default.dim(`Config: ${configPath}`));
         if (opts.tags)
             console.log(chalk_1.default.dim(`Tags:   ${opts.tags}`));
+        if (opts.sourceFile?.length)
+            console.log(chalk_1.default.dim(`Files:  ${opts.sourceFile.join(', ')}`));
+        if (opts.include?.length)
+            console.log(chalk_1.default.dim(`Include: ${opts.include.join(', ')}`));
         console.log('');
         const aiSummary = buildAiOpts(opts, config, configDir);
         const isTTY = process.stdout.isTTY ?? false;
         const outputFormat = program.opts().output;
         const onProgress = outputFormat === 'json' ? undefined : createProgressCallback(isTTY);
         const onAiProgress = outputFormat === 'json' ? undefined : createAiProgressCallback(isTTY);
-        const results = await (0, engine_1.status)(config, configDir, { tags: opts.tags, onProgress, onAiProgress, aiSummary });
+        const results = await (0, engine_1.status)(config, configDir, { tags: opts.tags, sourceFiles: opts.sourceFile, includePatterns: opts.include?.length ? opts.include : undefined, onProgress, onAiProgress, aiSummary });
         if (isTTY && outputFormat !== 'json')
             clearProgressLine();
         printResults(results, config.toolSettings?.outputLevel, outputFormat);
@@ -392,7 +524,7 @@ program
     const globalOpts = program.opts();
     try {
         const configPath = (0, config_1.resolveConfigPath)(globalOpts.config);
-        const config = (0, config_1.loadConfig)(configPath);
+        const config = loadConfigWithOverrides(configPath);
         const cliPublishOverrides = [
             ...(opts.testConfiguration ? [/^\d+$/.test(opts.testConfiguration)
                     ? `publishTestResults.testConfiguration.id=${opts.testConfiguration}`
@@ -452,6 +584,28 @@ program
             console.log(chalk_1.default.dim(`Run ID: ${result.runId}`));
             console.log(chalk_1.default.dim(`URL: ${result.runUrl}`));
         }
+        if (config.toolSettings?.outputLevel === 'diagnostic' && result.diagnostics) {
+            console.log('');
+            console.log(chalk_1.default.bold('Diagnostics:'));
+            if (result.diagnostics.sources.length) {
+                console.log(chalk_1.default.dim('  Sources:'));
+                for (const source of result.diagnostics.sources) {
+                    console.log(chalk_1.default.dim(`    ${path.relative(process.cwd(), source.filePath)} (${source.format})`));
+                }
+            }
+            if (result.diagnostics.configurationId) {
+                console.log(chalk_1.default.dim(`  Configuration ID: ${result.diagnostics.configurationId}`));
+            }
+            if (result.diagnostics.plannedRun) {
+                console.log(chalk_1.default.dim(`  Planned run: plan ${result.diagnostics.plannedRun.planId}, suite ${result.diagnostics.plannedRun.suiteId}, ${result.diagnostics.plannedRun.pointCount} point(s)`));
+            }
+            if (result.diagnostics.attachments) {
+                console.log(chalk_1.default.dim(`  Attachments: ${result.diagnostics.attachments.resultCount} result-level, ${result.diagnostics.attachments.runCount} run-level`));
+            }
+            if (result.diagnostics.analyzedFailures) {
+                console.log(chalk_1.default.dim(`  AI analyses: ${result.diagnostics.analyzedFailures}`));
+            }
+        }
         if (result.issuesSummary) {
             const s = result.issuesSummary;
             console.log('');
@@ -476,6 +630,7 @@ program
 const ACTION_SYMBOL = {
     created: chalk_1.default.green('+'),
     updated: chalk_1.default.blue('~'),
+    linked: chalk_1.default.green('↔'),
     pulled: chalk_1.default.cyan('↓'),
     skipped: chalk_1.default.dim('='),
     conflict: chalk_1.default.yellow('!'),
@@ -536,8 +691,10 @@ function printResults(results, outputLevel, outputFormat) {
         process.stdout.write(JSON.stringify(results, null, 2) + '\n');
         return;
     }
-    const counts = { created: 0, updated: 0, pulled: 0, skipped: 0, conflict: 0, removed: 0, error: 0 };
+    const counts = { created: 0, updated: 0, linked: 0, pulled: 0, skipped: 0, conflict: 0, removed: 0, error: 0 };
     const quiet = outputLevel === 'quiet';
+    const verbose = outputLevel === 'verbose';
+    const diagnostic = outputLevel === 'diagnostic';
     for (const r of results) {
         counts[r.action]++;
         // In quiet mode, only print actionable results (skip the '= skipped' lines)
@@ -555,6 +712,9 @@ function printResults(results, outputLevel, outputFormat) {
             case 'updated':
                 console.log(`${chalk_1.default.blue('~')} ${filePart} ${r.title}${idStr}`);
                 break;
+            case 'linked':
+                console.log(`${chalk_1.default.green('↔')} ${filePart} ${r.title}${idStr}${detailStr}`);
+                break;
             case 'pulled':
                 console.log(`${chalk_1.default.cyan('↓')} ${filePart} ${r.title}${idStr}${detailStr}`);
                 break;
@@ -571,11 +731,24 @@ function printResults(results, outputLevel, outputFormat) {
                 console.log(`${chalk_1.default.red('✗')} ${filePart} ${r.title}${idStr}${chalk_1.default.red(detailStr)}`);
                 break;
         }
+        if (r.targetSuitePath && (r.action === 'created' || r.action === 'updated' || r.action === 'conflict' || verbose || diagnostic)) {
+            console.log(chalk_1.default.dim(`    target suite: ${r.targetSuitePath}`));
+        }
+        if (r.previousSuitePath && (r.action === 'updated' || r.action === 'conflict' || diagnostic)) {
+            console.log(chalk_1.default.dim(`    previous suite: ${r.previousSuitePath}`));
+        }
+        if (diagnostic && r.changedFields?.length) {
+            console.log(chalk_1.default.dim(`    changed fields: ${r.changedFields.join(', ')}`));
+        }
+        if (diagnostic && r.detail && r.action !== 'linked' && r.action !== 'pulled' && r.action !== 'error') {
+            console.log(chalk_1.default.dim(`    detail: ${r.detail}`));
+        }
     }
     console.log('');
     const summary = [
         counts.created && chalk_1.default.green(`${counts.created} created`),
         counts.updated && chalk_1.default.blue(`${counts.updated} updated`),
+        counts.linked && chalk_1.default.green(`${counts.linked} linked`),
         counts.pulled && chalk_1.default.cyan(`${counts.pulled} pulled`),
         counts.skipped && chalk_1.default.dim(`${counts.skipped} skipped`),
         counts.conflict && chalk_1.default.yellow(`${counts.conflict} conflicts`),
@@ -597,10 +770,19 @@ program
     console.log('');
     // 1. Load config
     let config;
+    let validateDiagnostics;
     try {
         config = (0, config_1.loadConfig)(configPath);
         if (opts.configOverride?.length)
             (0, config_1.applyOverrides)(config, opts.configOverride);
+        const plans = config.testPlans ?? [config.testPlan];
+        validateDiagnostics = {
+            authType: config.auth.type,
+            localType: config.local.type,
+            syncTargetMode: config.syncTarget?.mode ?? 'suite',
+            planIds: plans.map((plan) => plan.id),
+            overrideCount: opts.configOverride?.length ?? 0,
+        };
         console.log(chalk_1.default.green('  ✓ Config is valid'));
     }
     catch (err) {
@@ -616,6 +798,10 @@ program
     }
     catch (err) {
         console.log(chalk_1.default.red(`  ✗ Azure connection failed: ${formatError(err)}`));
+        if (config.toolSettings?.outputLevel === 'diagnostic' && validateDiagnostics) {
+            console.log('');
+            printDiagnosticItems((0, cli_diagnostics_1.getValidateDiagnosticItems)(validateDiagnostics));
+        }
         process.exit(1);
     }
     // 3. Verify project
@@ -628,6 +814,10 @@ program
     }
     catch (err) {
         console.log(chalk_1.default.red(`  ✗ Project "${config.project}" not found: ${formatError(err)}`));
+        if (config.toolSettings?.outputLevel === 'diagnostic' && validateDiagnostics) {
+            console.log('');
+            printDiagnosticItems((0, cli_diagnostics_1.getValidateDiagnosticItems)(validateDiagnostics));
+        }
         process.exit(1);
     }
     // 4. Verify test plan(s)
@@ -644,6 +834,10 @@ program
             allPlansOk = false;
         }
     }
+    if (config.toolSettings?.outputLevel === 'diagnostic' && validateDiagnostics) {
+        console.log('');
+        printDiagnosticItems((0, cli_diagnostics_1.getValidateDiagnosticItems)(validateDiagnostics));
+    }
     if (!allPlansOk)
         process.exit(1);
     console.log('');
@@ -654,6 +848,8 @@ program
     .command('diff')
     .description('Show field-level diff between local specs and Azure DevOps')
     .option('--tags <expression>', 'Only check scenarios matching this tag expression')
+    .option('--source-file <path>', 'Restrict the operation to a specific local file (repeatable)', collect, [])
+    .option('--include <pattern>', 'Restrict the operation to files matching a glob pattern relative to config dir (repeatable)', collect, [])
     .option('--config-override <path=value>', 'Override a config value (repeatable)', collect, [])
     .option('--format <fmt>', 'Output format: text (default) or json')
     .option('--fail-on-drift', 'Exit with code 1 when any differences are found (useful as a CI quality gate)')
@@ -665,7 +861,7 @@ program
     const globalOpts = program.opts();
     try {
         const configPath = (0, config_1.resolveConfigPath)(globalOpts.config);
-        const config = (0, config_1.loadConfig)(configPath);
+        const config = loadConfigWithOverrides(configPath);
         if (opts.configOverride?.length)
             (0, config_1.applyOverrides)(config, opts.configOverride);
         const configDir = path.dirname(configPath);
@@ -673,19 +869,25 @@ program
         console.log(chalk_1.default.dim(`Config: ${configPath}`));
         if (opts.tags)
             console.log(chalk_1.default.dim(`Tags:   ${opts.tags}`));
+        if (opts.sourceFile?.length)
+            console.log(chalk_1.default.dim(`Files:  ${opts.sourceFile.join(', ')}`));
+        if (opts.include?.length)
+            console.log(chalk_1.default.dim(`Include: ${opts.include.join(', ')}`));
         console.log('');
         const aiSummary = buildAiOpts(opts, config, configDir);
-        const results = await (0, engine_1.status)(config, configDir, { tags: opts.tags, aiSummary });
+        const results = await (0, engine_1.status)(config, configDir, { tags: opts.tags, sourceFiles: opts.sourceFile, includePatterns: opts.include?.length ? opts.include : undefined, aiSummary });
         // --format json or global --output json
         const outputFormat = opts.format ?? program.opts().output;
         if (outputFormat === 'json') {
             const diffs = results
-                .filter((r) => r.action === 'updated' || r.action === 'conflict')
+                .filter((r) => r.action === 'created' || r.action === 'updated' || r.action === 'conflict')
                 .map((r) => ({
                 action: r.action,
                 azureId: r.azureId,
                 title: r.title,
                 filePath: r.filePath ? path.relative(process.cwd(), r.filePath) : '',
+                targetSuitePath: r.targetSuitePath,
+                previousSuitePath: r.previousSuitePath,
                 changedFields: r.changedFields ?? [],
                 diffDetail: r.diffDetail ?? [],
             }));
@@ -696,13 +898,19 @@ program
         }
         let anyDiff = false;
         for (const r of results) {
-            if (r.action !== 'updated' && r.action !== 'conflict')
+            if (r.action !== 'created' && r.action !== 'updated' && r.action !== 'conflict')
                 continue;
             anyDiff = true;
             const idStr = r.azureId ? chalk_1.default.dim(` [#${r.azureId}]`) : '';
             const filePart = r.filePath ? chalk_1.default.dim(path.relative(process.cwd(), r.filePath) + ':') : '';
-            const symbol = r.action === 'conflict' ? chalk_1.default.yellow('!') : chalk_1.default.blue('~');
+            const symbol = r.action === 'conflict' ? chalk_1.default.yellow('!') : r.action === 'created' ? chalk_1.default.green('+') : chalk_1.default.blue('~');
             console.log(`${symbol} ${filePart} ${r.title}${idStr}`);
+            if (r.targetSuitePath) {
+                console.log(chalk_1.default.dim(`    target suite: ${r.targetSuitePath}`));
+            }
+            if (r.previousSuitePath) {
+                console.log(chalk_1.default.dim(`    previous suite: ${r.previousSuitePath}`));
+            }
             if (r.changedFields?.length) {
                 console.log(chalk_1.default.dim(`    changed fields: ${r.changedFields.join(', ')}`));
             }
@@ -751,7 +959,7 @@ program
     const globalOpts = program.opts();
     try {
         const configPath = (0, config_1.resolveConfigPath)(globalOpts.config);
-        const config = (0, config_1.loadConfig)(configPath);
+        const config = loadConfigWithOverrides(configPath);
         if (opts.configOverride?.length)
             (0, config_1.applyOverrides)(config, opts.configOverride);
         const configDir = path.dirname(configPath);
@@ -876,7 +1084,7 @@ program
     const globalOpts = program.opts();
     try {
         const configPath = (0, config_1.resolveConfigPath)(globalOpts.config);
-        const config = (0, config_1.loadConfig)(configPath);
+        const config = loadConfigWithOverrides(configPath);
         if (opts.configOverride?.length)
             (0, config_1.applyOverrides)(config, opts.configOverride);
         const { AzureClient } = await Promise.resolve().then(() => __importStar(require('./azure/client')));
@@ -926,23 +1134,31 @@ program
     const globalOpts = program.opts();
     try {
         const configPath = (0, config_1.resolveConfigPath)(globalOpts.config);
-        const config = (0, config_1.loadConfig)(configPath);
+        const config = loadConfigWithOverrides(configPath);
         if (opts.configOverride?.length)
             (0, config_1.applyOverrides)(config, opts.configOverride);
         const { AzureClient } = await Promise.resolve().then(() => __importStar(require('./azure/client')));
         const { acGate, getWorkItemsByQuery, getWorkItemsByAreaPath } = await Promise.resolve().then(() => __importStar(require('./azure/work-items')));
         const client = await AzureClient.create(config);
         let storyIds = [];
+        let selectorMode = 'default-states';
+        let selectorValue = opts.states ?? 'Active,Resolved,Closed';
         if (opts.query) {
             const stories = await getWorkItemsByQuery(client, config.project, opts.query);
             storyIds = stories.map((s) => s.id);
+            selectorMode = 'query';
+            selectorValue = opts.query;
         }
         else if (opts.areaPath) {
             const stories = await getWorkItemsByAreaPath(client, config.project, opts.areaPath);
             storyIds = stories.map((s) => s.id);
+            selectorMode = 'area-path';
+            selectorValue = opts.areaPath;
         }
         else if (opts.storyIds) {
             storyIds = opts.storyIds.split(',').map((s) => parseInt(s.trim(), 10)).filter(Boolean);
+            selectorMode = 'story-ids';
+            selectorValue = opts.storyIds;
         }
         else {
             // Default: all active stories in project
@@ -951,6 +1167,7 @@ program
             const wiql = `SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = '${config.project.replace(/'/g, "''")}' AND [System.WorkItemType] = 'User Story' AND [System.State] IN (${stateList}) ORDER BY [System.Id]`;
             const stories = await getWorkItemsByQuery(client, config.project, wiql);
             storyIds = stories.map((s) => s.id);
+            selectorValue = states;
         }
         if (storyIds.length === 0) {
             console.log(chalk_1.default.yellow('No stories found to validate.'));
@@ -961,6 +1178,23 @@ program
         console.log(chalk_1.default.dim(`Stories: ${storyIds.length} to validate`));
         console.log('');
         const report = await acGate(client, config.project, storyIds, config.orgUrl);
+        if (config.toolSettings?.outputLevel === 'diagnostic') {
+            const noAc = report.failed.filter((r) => r.outcome === 'no-ac').length;
+            const noTc = report.failed.filter((r) => r.outcome === 'no-tc').length;
+            printDiagnosticItems((0, cli_diagnostics_1.getAcGateDiagnosticItems)({
+                selectorMode,
+                selectorValue,
+                states: selectorMode === 'default-states' ? selectorValue : undefined,
+                failMode: opts.failOnNoAc ? 'no-ac-only' : 'all-failures',
+                totalStories: storyIds.length,
+                passed: report.passed.length,
+                failed: report.failed.length,
+                noAc,
+                noTc,
+                overrideCount: opts.configOverride?.length ?? 0,
+            }));
+            console.log('');
+        }
         const outputFormat = globalOpts.output;
         if (outputFormat === 'json') {
             process.stdout.write(JSON.stringify(report, null, 2) + '\n');
@@ -1001,6 +1235,7 @@ program
     .command('stale')
     .description('List Azure DevOps Test Cases that have no corresponding local spec')
     .option('--tags <expression>', 'Only consider local specs matching this tag expression')
+    .option('--suites', 'Report orphaned suite memberships (affected by stalenessPolicy config)')
     .option('--retire', 'Automatically transition stale Test Cases to Closed state and tag ado-sync:retired')
     .option('--retire-state <state>', 'Target state when retiring (default: Closed)', 'Closed')
     .option('--dry-run', 'Show what --retire would do without making changes')
@@ -1009,7 +1244,7 @@ program
     const globalOpts = program.opts();
     try {
         const configPath = (0, config_1.resolveConfigPath)(globalOpts.config);
-        const config = (0, config_1.loadConfig)(configPath);
+        const config = loadConfigWithOverrides(configPath);
         if (opts.configOverride?.length)
             (0, config_1.applyOverrides)(config, opts.configOverride);
         const configDir = path.dirname(configPath);
@@ -1021,6 +1256,23 @@ program
             console.log(chalk_1.default.dim(`Retire: will transition to "${opts.retireState}"${opts.dryRun ? ' (dry-run)' : ''}`));
         console.log('');
         const staleCases = await (0, engine_1.detectStaleTestCases)(config, configDir, { tags: opts.tags });
+        if (config.toolSettings?.outputLevel === 'diagnostic') {
+            console.log(chalk_1.default.bold('Diagnostics:'));
+            for (const item of (0, cli_diagnostics_1.getStaleDiagnosticItems)({
+                syncTargetMode: config.syncTarget?.mode ?? 'suite',
+                planIds: (config.testPlans?.length ? config.testPlans : [config.testPlan]).map((plan) => plan.id),
+                markerPrefix: (0, id_markers_1.getPreferredMarkerTagPrefix)(config),
+                ownershipTag: (0, id_markers_1.getSyncTargetOwnershipTag)(config),
+                tagExpression: opts.tags,
+                staleCount: staleCases.length,
+                retireState: opts.retire ? opts.retireState : undefined,
+                dryRun: Boolean(opts.dryRun),
+                overrideCount: opts.configOverride?.length ?? 0,
+            })) {
+                console.log(chalk_1.default.dim(`  ${item.label}: ${item.value}`));
+            }
+            console.log('');
+        }
         const outputFormat = globalOpts.output;
         if (outputFormat === 'json') {
             process.stdout.write(JSON.stringify(staleCases, null, 2) + '\n');
@@ -1085,7 +1337,7 @@ program
     const globalOpts = program.opts();
     try {
         const configPath = (0, config_1.resolveConfigPath)(globalOpts.config);
-        const config = (0, config_1.loadConfig)(configPath);
+        const config = loadConfigWithOverrides(configPath);
         if (opts.configOverride?.length)
             (0, config_1.applyOverrides)(config, opts.configOverride);
         const configDir = path.dirname(configPath);
@@ -1095,6 +1347,23 @@ program
             console.log(chalk_1.default.dim(`Tags:   ${opts.tags}`));
         console.log('');
         const report = await (0, engine_1.coverageReport)(config, configDir, { tags: opts.tags });
+        const threshold = opts.failBelow ? parseInt(opts.failBelow, 10) : undefined;
+        if (config.toolSettings?.outputLevel === 'diagnostic') {
+            printDiagnosticItems((0, cli_diagnostics_1.getCoverageDiagnosticItems)({
+                localType: config.local.type,
+                syncTargetMode: config.syncTarget?.mode ?? 'suite',
+                tagExpression: opts.tags,
+                totalLocalSpecs: report.totalLocalSpecs,
+                linkedSpecs: report.linkedSpecs,
+                unlinkedSpecs: report.unlinkedSpecs,
+                storiesReferenced: report.storiesReferenced.length,
+                storiesCovered: report.storiesCovered.length,
+                storyPrefix: config.sync?.links?.find((link) => link.prefix === 'story')?.prefix ?? 'story',
+                failBelow: threshold,
+                overrideCount: opts.configOverride?.length ?? 0,
+            }));
+            console.log('');
+        }
         const outputFormat = globalOpts.output;
         if (outputFormat === 'json') {
             process.stdout.write(JSON.stringify(report, null, 2) + '\n');
@@ -1120,7 +1389,6 @@ program
                 console.log(chalk_1.default.dim('No @story: tags found — add @story:ID tags to specs to track story coverage.'));
             }
         }
-        const threshold = opts.failBelow ? parseInt(opts.failBelow, 10) : undefined;
         if (threshold !== undefined && report.specLinkRate < threshold) {
             console.error(chalk_1.default.red(`\nSpec link rate ${report.specLinkRate}% is below threshold ${threshold}%`));
             process.exit(1);
@@ -1147,7 +1415,7 @@ program
     const globalOpts = program.opts();
     try {
         const configPath = (0, config_1.resolveConfigPath)(globalOpts.config);
-        const config = (0, config_1.loadConfig)(configPath);
+        const config = loadConfigWithOverrides(configPath);
         if (opts.configOverride?.length)
             (0, config_1.applyOverrides)(config, opts.configOverride);
         const { trendReport, postTrendToWebhook } = await Promise.resolve().then(() => __importStar(require('./azure/test-runs')));
@@ -1161,6 +1429,24 @@ program
             topN: parseInt(opts.top, 10),
             runNameFilter: opts.runName,
         });
+        const threshold = opts.failBelow ? parseInt(opts.failBelow, 10) : undefined;
+        if (config.toolSettings?.outputLevel === 'diagnostic') {
+            printDiagnosticItems((0, cli_diagnostics_1.getTrendDiagnosticItems)({
+                days: parseInt(opts.days, 10),
+                maxRuns: parseInt(opts.maxRuns, 10),
+                topN: parseInt(opts.top, 10),
+                runNameFilter: opts.runName,
+                webhookType: opts.webhookUrl ? (opts.webhookType ?? 'slack') : undefined,
+                failOnFlaky: Boolean(opts.failOnFlaky),
+                failBelow: threshold,
+                runsAnalyzed: report.runsAnalyzed,
+                totalResults: report.totalResults,
+                flakyCount: report.flakyTests.length,
+                failingCount: report.topFailingTests.length,
+                overrideCount: opts.configOverride?.length ?? 0,
+            }));
+            console.log('');
+        }
         const outputFormat = globalOpts.output;
         if (outputFormat === 'json') {
             process.stdout.write(JSON.stringify(report, null, 2) + '\n');
@@ -1203,7 +1489,6 @@ program
             console.error(chalk_1.default.red(`\n${report.flakyTests.length} flaky test${report.flakyTests.length !== 1 ? 's' : ''} detected.`));
             process.exit(1);
         }
-        const threshold = opts.failBelow ? parseInt(opts.failBelow, 10) : undefined;
         if (threshold !== undefined && report.overallPassRate < threshold) {
             console.error(chalk_1.default.red(`\nOverall pass rate ${report.overallPassRate}% is below threshold ${threshold}%`));
             process.exit(1);
@@ -1218,7 +1503,12 @@ program
     .command('watch')
     .description('Watch local spec files for changes and auto-push on save')
     .option('--dry-run', 'Show what would change without making any modifications')
+    .option('--create-only', 'Only create test cases for unlinked local specs during each watched push')
+    .option('--link-only', 'Only restore local IDs during each watched push')
+    .option('--update-only', 'Only update linked test cases during each watched push')
     .option('--tags <expression>', 'Only sync scenarios matching this tag expression')
+    .option('--source-file <path>', 'Restrict watch and push to a specific local file (repeatable)', collect, [])
+    .option('--include <pattern>', 'Restrict the operation to files matching a glob pattern relative to config dir (repeatable)', collect, [])
     .option('--debounce <ms>', 'Debounce delay in milliseconds before running push (default: 800)', '800')
     .option('--config-override <path=value>', 'Override a config value (repeatable)', collect, [])
     .option('--ai-provider <provider>', 'AI provider for test step generation')
@@ -1229,10 +1519,12 @@ program
     const globalOpts = program.opts();
     try {
         const configPath = (0, config_1.resolveConfigPath)(globalOpts.config);
-        const config = (0, config_1.loadConfig)(configPath);
+        const config = loadConfigWithOverrides(configPath);
         if (opts.configOverride?.length)
             (0, config_1.applyOverrides)(config, opts.configOverride);
+        (0, engine_1.validatePushModeOptions)(opts);
         const configDir = path.dirname(configPath);
+        const sourceFiles = normalizeSourceFilesForCli(opts.sourceFile, configDir);
         const debounceMs = parseInt(opts.debounce ?? '800', 10);
         console.log(chalk_1.default.bold('ado-sync watch'));
         console.log(chalk_1.default.dim(`Config:  ${configPath}`));
@@ -1240,8 +1532,18 @@ program
         console.log(chalk_1.default.dim(`Plan:    ${config.testPlan.id}`));
         if (opts.dryRun)
             console.log(chalk_1.default.yellow('Dry run — no changes will be made'));
+        if (opts.createOnly)
+            console.log(chalk_1.default.dim('Mode:    create-only'));
+        if (opts.linkOnly)
+            console.log(chalk_1.default.dim('Mode:    link-only'));
+        if (opts.updateOnly)
+            console.log(chalk_1.default.dim('Mode:    update-only'));
         if (opts.tags)
             console.log(chalk_1.default.dim(`Tags:    ${opts.tags}`));
+        if (sourceFiles?.length)
+            console.log(chalk_1.default.dim(`Files:   ${sourceFiles.join(', ')}`));
+        if (opts.include?.length)
+            console.log(chalk_1.default.dim(`Include: ${opts.include.join(', ')}`));
         console.log('');
         console.log(chalk_1.default.dim(`Watching ${configDir} for changes... (Ctrl+C to stop)`));
         console.log('');
@@ -1259,7 +1561,12 @@ program
                 const onProgress = createProgressCallback(isTTY);
                 const results = await (0, engine_1.push)(config, configDir, {
                     dryRun: opts.dryRun,
+                    createOnly: opts.createOnly,
+                    linkOnly: opts.linkOnly,
+                    updateOnly: opts.updateOnly,
                     tags: opts.tags,
+                    sourceFiles,
+                    includePatterns: opts.include?.length ? opts.include : undefined,
                     onProgress,
                     aiSummary,
                 });
@@ -1287,6 +1594,11 @@ program
             const skipPatterns = ['.ado-sync-cache.json', 'ado-sync.json', 'ado-sync.yml', 'node_modules'];
             if (skipPatterns.some((p) => filename.includes(p)))
                 return;
+            if (sourceFiles?.length) {
+                const changedFilePath = path.normalize(path.resolve(configDir, filename));
+                if (!sourceFiles.includes(changedFilePath))
+                    return;
+            }
             onChange();
         });
         // Keep process alive
@@ -1315,7 +1627,7 @@ program
     const globalOpts = program.opts();
     try {
         const configPath = (0, config_1.resolveConfigPath)(globalOpts.config);
-        const config = (0, config_1.loadConfig)(configPath);
+        const config = loadConfigWithOverrides(configPath);
         if (opts.configOverride?.length)
             (0, config_1.applyOverrides)(config, opts.configOverride);
         if (!opts.hours && !opts.days) {