mustflow 1.18.16 → 1.30.0

package/dist/cli/commands/run.js

@@ -1,5 +1,4 @@
 import { spawnSync } from 'node:child_process';
-import path from 'node:path';
 import { runCheck } from './check.js';
 import { runClassify } from './classify.js';
 import { runContext } from './context.js';
@@ -12,22 +11,16 @@ import { runStatus } from './status.js';
 import { runUpdate } from './update.js';
 import { runVersionSources } from './version-sources.js';
 import { canRunMustflowBuiltinInProcess, isMustflowBinName } from '../../core/command-classification.js';
-import { resolveSafeProjectCwd } from '../../core/command-cwd.js';
-import { evaluateCommandIntentEligibility } from '../../core/command-intent-eligibility.js';
+import { createCommandEnv } from '../../core/command-env.js';
 import { printUsageError, renderCliError, renderHelp } from '../lib/cli-output.js';
-import { isRecord, readCommandContract, readMustflowConfigIfExists, readPositiveInteger, readString, readStringArray, } from '../../core/config-loading.js';
+import { readCommandContract, readMustflowConfigIfExists } from '../../core/config-loading.js';
 import { resolveRunReceiptRetentionPolicy } from '../../core/retention-policy.js';
 import { t } from '../lib/i18n.js';
 import { getPackageVersion } from '../lib/package-info.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
+import { createRunPlan, createRunPreview, isMustflowBuiltinIntent, renderRunPreviewText, } from '../lib/run-plan.js';
 import { createRunReceipt, writeRunReceipt } from '../../core/run-receipt.js';
-function getSuccessExitCodes(intent) {
-    const value = intent.success_exit_codes;
-    if (!Array.isArray(value) || value.length === 0 || value.some((entry) => !Number.isInteger(entry))) {
-        return [0];
-    }
-    return value.map(Number);
-}
+import { finishRunWriteTracking, startRunWriteTracking } from '../../core/run-write-drift.js';
 function emitOutput(reporter, output, stream) {
     if (!output) {
         return;
@@ -64,57 +57,6 @@ function terminateProcessTree(pid) {
 function getKillMethod() {
     return process.platform === 'win32' ? 'taskkill_process_tree' : 'process_group_sigterm';
 }
-function getPathEnvKey(env) {
-    return Object.keys(env).find((key) => key.toLowerCase() === 'path') ?? 'PATH';
-}
-function sameResolvedPath(left, right) {
-    const resolvedLeft = path.resolve(left);
-    const resolvedRight = path.resolve(right);
-    return process.platform === 'win32'
-        ? resolvedLeft.toLowerCase() === resolvedRight.toLowerCase()
-        : resolvedLeft === resolvedRight;
-}
-function createCommandEnv(projectRoot) {
-    const env = { ...process.env };
-    const pathKey = getPathEnvKey(env);
-    const localBinPath = path.join(projectRoot, 'node_modules', '.bin');
-    const currentPath = env[pathKey];
-    if (currentPath) {
-        env[pathKey] = currentPath
-            .split(path.delimiter)
-            .filter((entry) => entry.length > 0 && !sameResolvedPath(entry, localBinPath))
-            .join(path.delimiter);
-    }
-    return env;
-}
-function shouldUseShellForArgvExecutable(executablePath) {
-    return process.platform === 'win32' && executablePath.toLowerCase().endsWith('.cmd');
-}
-function isMustflowBuiltinIntent(intent) {
-    return readString(intent, 'kind') === 'mustflow_builtin';
-}
-function resolveCurrentCliEntrypoint() {
-    const entrypoint = process.argv[1];
-    return entrypoint ? path.resolve(entrypoint) : undefined;
-}
-function resolveArgvCommand(intent, commandArgv) {
-    const [command = '', ...args] = commandArgv;
-    if (isMustflowBuiltinIntent(intent) && isMustflowBinName(command)) {
-        const entrypoint = resolveCurrentCliEntrypoint();
-        if (entrypoint) {
-            return {
-                executable: process.execPath,
-                args: [entrypoint, ...args],
-                shell: false,
-            };
-        }
-    }
-    return {
-        executable: command,
-        args,
-        shell: shouldUseShellForArgvExecutable(command),
-    };
-}
 function createBufferedReporter() {
     const stdout = [];
     const stderr = [];
@@ -260,15 +202,66 @@ function getRunStatus(error, exitCode, successExitCodes) {
     }
     return exitCode !== null && successExitCodes.includes(exitCode) ? 'passed' : 'failed';
 }
+function getRunPlanDetail(plan, lang, fallbackKey) {
+    return plan.detail ?? t(lang, fallbackKey);
+}
+function reportRunPlanFailure(plan, reporter, lang) {
+    let message;
+    switch (plan.reasonCode) {
+        case 'status_not_configured':
+            message = t(lang, 'run.error.statusNotConfigured', { intent: plan.intentName, status: plan.intentStatus ?? 'unknown' });
+            break;
+        case 'lifecycle_not_oneshot':
+            message = t(lang, 'run.error.lifecycleNotOneshot', { intent: plan.intentName, lifecycle: plan.lifecycle ?? 'unknown' });
+            break;
+        case 'run_policy_not_agent_allowed':
+            message = t(lang, 'run.error.runPolicy', { intent: plan.intentName });
+            break;
+        case 'stdin_not_closed':
+            message = t(lang, 'run.error.stdin', { intent: plan.intentName });
+            break;
+        case 'missing_timeout':
+            message = t(lang, 'run.error.timeout', { intent: plan.intentName });
+            break;
+        case 'missing_command_source':
+            message = t(lang, 'run.error.commandSource', { intent: plan.intentName });
+            break;
+        case 'unsafe_intent_name':
+            message = t(lang, 'run.error.unsafeIntent', {
+                intent: plan.intentName,
+                detail: getRunPlanDetail(plan, lang, 'run.error.unsafeIntentDetail'),
+            });
+            break;
+        case 'blocked_shell_background_pattern':
+            message = t(lang, 'run.error.blockedShellBackground', {
+                intent: plan.intentName,
+                detail: getRunPlanDetail(plan, lang, 'run.error.blockedShellBackgroundDetail'),
+            });
+            break;
+        case 'cwd_outside_project':
+            message = t(lang, 'run.error.cwdOutsideProject', {
+                intent: plan.intentName,
+                detail: getRunPlanDetail(plan, lang, 'run.error.cwdOutsideProjectDetail'),
+            });
+            break;
+        case 'intent_not_table':
+        default:
+            message = t(lang, 'run.error.unknownIntent', { intent: plan.intentName });
+            break;
+    }
+    reporter.stderr(renderCliError(message, 'mf help commands', lang));
+}
 export function getRunHelp(lang = 'en') {
     return renderHelp({
         usage: 'mf run <intent> [options]',
         summary: t(lang, 'run.help.summary'),
         options: [
+            { label: '--dry-run', description: t(lang, 'run.help.option.dryRun') },
+            { label: '--plan-only', description: t(lang, 'run.help.option.planOnly') },
             { label: '--json', description: t(lang, 'run.help.option.json') },
             { label: '-h, --help', description: t(lang, 'cli.option.help') },
         ],
-        examples: ['mf run test', 'mf run lint --json', 'mf run mustflow_check'],
+        examples: ['mf run test', 'mf run lint --json', 'mf run mustflow_check --dry-run --json'],
         exitCodes: [
             {
                 label: '0',
@@ -293,13 +286,20 @@ export async function runRun(args, reporter, lang = 'en') {
         reporter.stdout(getRunHelp(lang));
         return 0;
     }
-    const supportedOptions = new Set(['--json']);
+    const supportedOptions = new Set(['--json', '--dry-run', '--plan-only']);
     const unsupported = args.filter((arg) => arg.startsWith('-') && !supportedOptions.has(arg));
     if (unsupported.length > 0) {
         printUsageError(reporter, t(lang, 'cli.error.unknownOption', { option: unsupported[0] }), 'mf run --help', getRunHelp(lang), lang);
         return 1;
     }
     const json = args.includes('--json');
+    const dryRun = args.includes('--dry-run');
+    const planOnly = args.includes('--plan-only');
+    const previewMode = dryRun ? 'dry-run' : planOnly ? 'plan-only' : null;
+    if (dryRun && planOnly) {
+        printUsageError(reporter, t(lang, 'run.error.conflictingPreviewModes'), 'mf run --help', getRunHelp(lang), lang);
+        return 1;
+    }
     const positional = args.filter((arg) => !supportedOptions.has(arg));
     const [intentName, ...extra] = positional;
     if (!intentName) {
@@ -312,78 +312,36 @@ export async function runRun(args, reporter, lang = 'en') {
     }
     const projectRoot = resolveMustflowRoot();
     const contract = readCommandContract(projectRoot);
-    const runReceiptPolicy = resolveRunReceiptRetentionPolicy(readMustflowConfigIfExists(projectRoot));
-    const intent = contract.intents[intentName];
-    if (!isRecord(intent)) {
-        reporter.stderr(renderCliError(t(lang, 'run.error.unknownIntent', { intent: intentName }), 'mf help commands', lang));
-        return 1;
-    }
-    const eligibility = evaluateCommandIntentEligibility(intentName, intent);
-    const intentStatus = readString(intent, 'status') ?? 'unknown';
-    const lifecycle = readString(intent, 'lifecycle');
-    const runPolicy = readString(intent, 'run_policy');
-    const timeoutSeconds = readPositiveInteger(intent, 'timeout_seconds');
-    if (!eligibility.ok) {
-        if (eligibility.code === 'status_not_configured') {
-            reporter.stderr(renderCliError(t(lang, 'run.error.statusNotConfigured', { intent: intentName, status: intentStatus }), 'mf help commands', lang));
-            return 1;
-        }
-        if (eligibility.code === 'lifecycle_not_oneshot') {
-            reporter.stderr(renderCliError(t(lang, 'run.error.lifecycleNotOneshot', { intent: intentName, lifecycle: lifecycle ?? 'unknown' }), 'mf help commands', lang));
-            return 1;
-        }
-        if (eligibility.code === 'run_policy_not_agent_allowed') {
-            reporter.stderr(renderCliError(t(lang, 'run.error.runPolicy', { intent: intentName }), 'mf help commands', lang));
-            return 1;
-        }
-        if (eligibility.code === 'stdin_not_closed') {
-            reporter.stderr(renderCliError(t(lang, 'run.error.stdin', { intent: intentName }), 'mf help commands', lang));
-            return 1;
-        }
-        if (eligibility.code === 'missing_timeout') {
-            reporter.stderr(renderCliError(t(lang, 'run.error.timeout', { intent: intentName }), 'mf help commands', lang));
-            return 1;
+    const plan = createRunPlan(projectRoot, contract, intentName);
+    if (previewMode) {
+        if (json) {
+            reporter.stdout(JSON.stringify(createRunPreview(plan, previewMode), null, 2));
         }
-        if (eligibility.code === 'missing_command_source') {
-            reporter.stderr(renderCliError(t(lang, 'run.error.commandSource', { intent: intentName }), 'mf help commands', lang));
-            return 1;
+        else {
+            reporter.stdout(renderRunPreviewText(plan, previewMode));
         }
-        if (eligibility.code === 'unsafe_intent_name') {
-            reporter.stderr(renderCliError(`Intent ${intentName} has an unsafe name. ${eligibility.detail ?? 'Use a shell-safe intent name.'}`, 'mf help commands', lang));
-            return 1;
-        }
-        if (eligibility.code === 'blocked_shell_background_pattern') {
-            reporter.stderr(renderCliError(`Intent ${intentName} is blocked. ${eligibility.detail ?? 'Shell commands must not spawn background work.'}`, 'mf help commands', lang));
-            return 1;
-        }
-        reporter.stderr(renderCliError(t(lang, 'run.error.unknownIntent', { intent: intentName }), 'mf help commands', lang));
-        return 1;
+        return plan.ok ? 0 : 1;
     }
-    const maxOutputBytes = readPositiveInteger(intent, 'max_output_bytes') ?? readPositiveInteger(contract.defaults, 'max_output_bytes') ?? 1_048_576;
-    if (!timeoutSeconds) {
-        reporter.stderr(renderCliError(t(lang, 'run.error.timeout', { intent: intentName }), 'mf help commands', lang));
+    if (!plan.ok) {
+        reportRunPlanFailure(plan, reporter, lang);
         return 1;
     }
-    const cwd = resolveSafeProjectCwd(projectRoot, readString(intent, 'cwd') ?? readString(contract.defaults, 'default_cwd'));
-    const successExitCodes = getSuccessExitCodes(intent);
-    const argv = readStringArray(intent, 'argv');
-    const commandArgv = argv && argv.length > 0 ? argv : undefined;
-    const shellCommand = intent.mode === 'shell' ? readString(intent, 'cmd') : undefined;
-    const env = createCommandEnv(projectRoot);
-    const lifecycleValue = lifecycle ?? 'oneshot';
-    const runPolicyValue = runPolicy ?? 'agent_allowed';
-    const mode = commandArgv ? 'argv' : 'shell';
+    const runReceiptPolicy = resolveRunReceiptRetentionPolicy(readMustflowConfigIfExists(projectRoot));
+    const env = createCommandEnv(projectRoot, { policy: plan.envPolicy, allowlist: plan.envAllowlist });
+    const lifecycleValue = plan.lifecycle ?? 'oneshot';
+    const runPolicyValue = plan.runPolicy ?? 'agent_allowed';
+    const writeTracker = startRunWriteTracking(projectRoot, contract, intentName);
     const startedAt = new Date();
-    const argvCommand = commandArgv ? resolveArgvCommand(intent, commandArgv) : undefined;
-    const result = commandArgv && isMustflowBuiltinIntent(intent)
-        ? ((await runBuiltinArgvInProcess(commandArgv, cwd, lang)) ??
-            runArgvCommand(argvCommand, cwd, maxOutputBytes, env, timeoutSeconds))
-        : commandArgv
-            ? runArgvCommand(argvCommand, cwd, maxOutputBytes, env, timeoutSeconds)
-            : runShellCommand(shellCommand, cwd, maxOutputBytes, env, timeoutSeconds);
+    const result = plan.commandArgv && isMustflowBuiltinIntent(plan.intent)
+        ? ((await runBuiltinArgvInProcess(plan.commandArgv, plan.cwd, lang)) ??
+            runArgvCommand(plan.argvCommand, plan.cwd, plan.maxOutputBytes, env, plan.timeoutSeconds))
+        : plan.commandArgv
+            ? runArgvCommand(plan.argvCommand, plan.cwd, plan.maxOutputBytes, env, plan.timeoutSeconds)
+            : runShellCommand(plan.shellCommand, plan.cwd, plan.maxOutputBytes, env, plan.timeoutSeconds);
     const finishedAt = new Date();
+    const writeDrift = finishRunWriteTracking(writeTracker);
     const exitCode = typeof result.status === 'number' ? result.status : null;
-    const runStatus = getRunStatus(result.error, exitCode, successExitCodes);
+    const runStatus = getRunStatus(result.error, exitCode, plan.successExitCodes);
     let killMethod = null;
     if (runStatus === 'timed_out') {
         killMethod = getKillMethod();
@@ -396,21 +354,24 @@ export async function runRun(args, reporter, lang = 'en') {
         startedAt,
         finishedAt,
         projectRoot,
-        cwd,
+        cwd: plan.cwd,
         lifecycle: lifecycleValue,
         runPolicy: runPolicyValue,
-        mode,
-        argv: commandArgv,
-        cmd: shellCommand,
-        timeoutSeconds,
-        maxOutputBytes,
-        successExitCodes,
+        mode: plan.mode,
+        argv: plan.commandArgv,
+        cmd: plan.shellCommand,
+        envPolicy: plan.envPolicy,
+        envAllowlist: plan.envAllowlist,
+        timeoutSeconds: plan.timeoutSeconds,
+        maxOutputBytes: plan.maxOutputBytes,
+        successExitCodes: plan.successExitCodes,
         exitCode,
         signal: result.signal,
         error: result.error?.message ?? null,
         killMethod,
         stdout: result.stdout,
         stderr: result.stderr,
+        writeDrift,
         stdoutTailBytes: runReceiptPolicy.stdoutTailBytes,
         stderrTailBytes: runReceiptPolicy.stderrTailBytes,
     });
@@ -424,7 +385,7 @@ export async function runRun(args, reporter, lang = 'en') {
     if (result.error) {
         const errorWithCode = result.error;
         if (errorWithCode.code === 'ETIMEDOUT') {
-            reporter.stderr(t(lang, 'run.error.timedOut', { intent: intentName, seconds: timeoutSeconds }));
+            reporter.stderr(t(lang, 'run.error.timedOut', { intent: intentName, seconds: plan.timeoutSeconds }));
             return 1;
         }
         reporter.stderr(t(lang, 'run.error.startFailed', { intent: intentName, message: result.error.message }));

package/dist/cli/commands/update.js

@@ -8,6 +8,7 @@ import { t } from '../lib/i18n.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
 import { getDefaultTemplate, getTemplateFiles, skillNameForTemplatePath } from '../lib/templates.js';
 import { readTomlFile, stringifyToml } from '../lib/toml.js';
+import { createUpdateDiffPreview, shouldPreviewUpdateDiff } from '../lib/update-diff-preview.js';
 const UPDATE_SCHEMA_VERSION = '1';
 const CUSTOMIZED_LOCK_ACTION = 'customized';
 const UPDATE_POLICY = {
@@ -25,6 +26,7 @@ export function getUpdateHelp(lang = 'en') {
         summary: t(lang, 'update.help.summary'),
         options: [
             { label: '--dry-run', description: t(lang, 'update.help.option.dryRun') },
+            { label: '--diff', description: t(lang, 'update.help.option.diff') },
             {
                 label: '--apply',
                 description: t(lang, 'update.help.option.apply'),
@@ -32,7 +34,7 @@ export function getUpdateHelp(lang = 'en') {
             { label: '--json', description: t(lang, 'cli.option.json') },
             { label: '-h, --help', description: t(lang, 'cli.option.help') },
         ],
-        examples: ['mf update --dry-run', 'mf update --dry-run --json', 'mf update --apply'],
+        examples: ['mf update --dry-run', 'mf update --dry-run --diff', 'mf update --dry-run --diff --json', 'mf update --apply'],
         exitCodes: [
             {
                 label: '0',
@@ -86,7 +88,27 @@ function templateTargetSafetyIssue(projectRoot, targetPath, allowMissingLeaf) {
         return error instanceof Error ? error.message : String(error);
     }
 }
-export function planUpdate(projectRoot) {
+function createPlanItem(source, action, reason) {
+    return {
+        relativePath: source.relativePath,
+        sourceKind: source.sourceKind,
+        source,
+        action,
+        reason,
+    };
+}
+function publicPlanItem(item) {
+    return {
+        relativePath: item.relativePath,
+        sourceKind: item.sourceKind,
+        action: item.action,
+        reason: item.reason,
+    };
+}
+function publicPlanItems(items) {
+    return items.map((item) => publicPlanItem(item));
+}
+function createUpdatePlan(projectRoot) {
     const lockResult = readManifestLock(projectRoot);
     if (lockResult.kind === 'missing') {
         return { items: [], error: `Missing ${MANIFEST_LOCK_RELATIVE_PATH}` };
@@ -111,94 +133,68 @@ export function planUpdate(projectRoot) {
         ensureInside(projectRoot, targetPath);
         const unsafeTargetReason = templateTargetSafetyIssue(projectRoot, targetPath, true);
         if (unsafeTargetReason) {
-            items.push({
-                relativePath: source.relativePath,
-                sourceKind: source.sourceKind,
-                action: 'blocked-local-change',
-                reason: unsafeTargetReason,
-            });
+            items.push(createPlanItem(source, 'blocked-local-change', unsafeTargetReason));
             continue;
         }
         if (!existsSync(targetPath)) {
             if (lockedFile) {
-                items.push({
-                    relativePath: source.relativePath,
-                    sourceKind: source.sourceKind,
-                    action: 'blocked-local-change',
-                    reason: 'target file is missing but tracked by the manifest lock',
-                });
+                items.push(createPlanItem(source, 'blocked-local-change', 'target file is missing but tracked by the manifest lock'));
                 continue;
             }
-            items.push({
-                relativePath: source.relativePath,
-                sourceKind: source.sourceKind,
-                action: 'create',
-                reason: 'target file is missing',
-            });
+            items.push(createPlanItem(source, 'create', 'target file is missing'));
             continue;
         }
         const currentHash = sha256File(targetPath);
         const templateHash = templateFileHash(source);
         if (!lockedFile && currentHash !== templateHash) {
-            items.push({
-                relativePath: source.relativePath,
-                sourceKind: source.sourceKind,
-                action: 'blocked-local-change',
-                reason: 'target file exists but is not tracked by the manifest lock',
-            });
+            items.push(createPlanItem(source, 'blocked-local-change', 'target file exists but is not tracked by the manifest lock'));
             continue;
         }
         if (lockedFile && currentHash !== lockedFile.contentHash) {
-            items.push({
-                relativePath: source.relativePath,
-                sourceKind: source.sourceKind,
-                action: 'blocked-local-change',
-                reason: 'current file differs from the manifest lock baseline',
-            });
+            items.push(createPlanItem(source, 'blocked-local-change', 'current file differs from the manifest lock baseline'));
             continue;
         }
         if (lockedFile?.lastAction === CUSTOMIZED_LOCK_ACTION && currentHash !== templateHash) {
-            items.push({
-                relativePath: source.relativePath,
-                sourceKind: source.sourceKind,
-                action: 'unchanged',
-                reason: 'manifest lock marks this file as customized and current file matches that baseline',
-            });
+            items.push(createPlanItem(source, 'unchanged', 'manifest lock marks this file as customized and current file matches that baseline'));
             continue;
         }
         if (lockedFile?.source === 'managed_block' && currentHash !== templateHash) {
-            items.push({
-                relativePath: source.relativePath,
-                sourceKind: source.sourceKind,
-                action: 'manual-review',
-                reason: 'managed block requires a block-level manifest baseline',
-            });
+            items.push(createPlanItem(source, 'manual-review', 'managed block requires a block-level manifest baseline'));
             continue;
         }
         if (currentHash !== templateHash) {
-            items.push({
-                relativePath: source.relativePath,
-                sourceKind: source.sourceKind,
-                action: 'update',
-                reason: 'template content differs from current file',
-            });
+            items.push(createPlanItem(source, 'update', 'template content differs from current file'));
             continue;
         }
-        items.push({
-            relativePath: source.relativePath,
-            sourceKind: source.sourceKind,
-            action: 'unchanged',
-            reason: 'current file matches the bundled template',
-        });
+        items.push(createPlanItem(source, 'unchanged', 'current file matches the bundled template'));
     }
     return { items };
 }
+export function planUpdate(projectRoot) {
+    const plan = createUpdatePlan(projectRoot);
+    return {
+        items: publicPlanItems(plan.items),
+        ...(plan.error ? { error: plan.error } : {}),
+    };
+}
 function printItems(title, items, reporter) {
     reporter.stdout(`${title}: ${items.length}`);
     for (const item of items) {
         reporter.stdout(`- ${item.relativePath} (${item.reason})`);
     }
 }
+function withDiffPreviews(projectRoot, items) {
+    return items.map((item) => {
+        const publicItem = publicPlanItem(item);
+        if (!shouldPreviewUpdateDiff(item.action)) {
+            return publicItem;
+        }
+        return {
+            ...publicItem,
+            diff_preview: createUpdateDiffPreview(projectRoot, item),
+        };
+    });
+}
 export function summarizePlan(items) {
     return {
         blockedLocalChanges: items.filter((item) => item.action === 'blocked-local-change').length,
@@ -369,16 +365,37 @@ function printPlan(output, reporter, lang) {
         reporter.stdout(t(lang, 'update.plan.noUpdates'));
     }
 }
+function printDiffPreviews(items, reporter, lang) {
+    const itemsWithDiff = items.filter((item) => item.diff_preview);
+    if (itemsWithDiff.length === 0) {
+        return;
+    }
+    reporter.stdout(t(lang, 'update.diff.title'));
+    for (const item of itemsWithDiff) {
+        const preview = item.diff_preview;
+        if (!preview) {
+            continue;
+        }
+        if (!preview.available) {
+            reporter.stdout(`# ${item.relativePath}: ${t(lang, 'update.diff.unavailable', { reason: preview.reason ?? 'unknown' })}`);
+            continue;
+        }
+        for (const line of preview.lines) {
+            reporter.stdout(line);
+        }
+    }
+}
 export function runUpdate(args, reporter, lang = 'en') {
     if (args.includes('--help') || args.includes('-h')) {
         reporter.stdout(getUpdateHelp(lang));
         return 0;
     }
-    const supported = new Set(['--dry-run', '--apply', '--json']);
+    const supported = new Set(['--dry-run', '--apply', '--json', '--diff']);
     const unsupported = args.filter((arg) => !supported.has(arg));
     const wantsJson = args.includes('--json');
     const wantsDryRun = args.includes('--dry-run');
     const wantsApply = args.includes('--apply');
+    const wantsDiff = args.includes('--diff');
     const requestedMode = getRequestedMode(wantsDryRun, wantsApply);
     if (unsupported.length > 0) {
         printUsageError(reporter, t(lang, 'cli.error.unknownOption', { option: unsupported[0] }), 'mf update --help', getUpdateHelp(lang), lang);
@@ -393,6 +410,15 @@ export function runUpdate(args, reporter, lang = 'en') {
         printUsageError(reporter, error, 'mf update --help', getUpdateHelp(lang), lang);
         return 1;
     }
+    if (wantsDiff && !wantsDryRun) {
+        const error = t(lang, 'update.error.diffRequiresDryRun');
+        if (wantsJson) {
+            reporter.stdout(JSON.stringify(withMode(planOutput([], error, false), requestedMode), null, 2));
+            return 1;
+        }
+        printUsageError(reporter, error, 'mf update --help', getUpdateHelp(lang), lang);
+        return 1;
+    }
     if (!wantsDryRun && !wantsApply) {
         const error = t(lang, 'update.error.missingMode');
         if (wantsJson) {
@@ -403,22 +429,26 @@ export function runUpdate(args, reporter, lang = 'en') {
         return 1;
     }
     const projectRoot = resolveMustflowRoot();
-    const plan = planUpdate(projectRoot);
+    const plan = createUpdatePlan(projectRoot);
     if (plan.error) {
         if (wantsJson) {
-            reporter.stdout(JSON.stringify(withMode(planOutput(plan.items, plan.error, false), requestedMode), null, 2));
+            reporter.stdout(JSON.stringify(withMode(planOutput(publicPlanItems(plan.items), plan.error, false), requestedMode), null, 2));
             return 1;
         }
         reporter.stderr(plan.error);
         return 1;
     }
-    const dryRunOutput = withMode(planOutput(plan.items, undefined, false), requestedMode);
+    const outputItems = wantsDiff ? withDiffPreviews(projectRoot, plan.items) : publicPlanItems(plan.items);
+    const dryRunOutput = withMode(planOutput(outputItems, undefined, false), requestedMode);
     if (wantsDryRun) {
         if (wantsJson) {
             reporter.stdout(JSON.stringify(dryRunOutput, null, 2));
             return dryRunOutput.ok ? 0 : 1;
         }
         printPlan(dryRunOutput, reporter, lang);
+        if (wantsDiff) {
+            printDiffPreviews(dryRunOutput.items, reporter, lang);
+        }
         reporter.stdout(t(lang, 'update.plan.noFilesWritten'));
         return dryRunOutput.ok ? 0 : 1;
     }
@@ -437,7 +467,7 @@ export function runUpdate(args, reporter, lang = 'en') {
             stdout: () => undefined,
             stderr: (message) => reporter.stderr(message),
         }, lang);
-        reporter.stdout(JSON.stringify(withMode(planOutput(plan.items, undefined, applyResult.wroteFiles), 'apply'), null, 2));
+        reporter.stdout(JSON.stringify(withMode(planOutput(publicPlanItems(plan.items), undefined, applyResult.wroteFiles), 'apply'), null, 2));
         return 0;
     }
     const applyResult = applyUpdate(projectRoot, plan.items, reporter, lang);