mustflow 2.103.15 → 2.103.20

package/README.md

@@ -129,6 +129,7 @@ mustflow installs and validates an agent workflow for user projects.
   config/schema churn, and broad structural changes before treating added complexity as free.
 - Lists, suggests, and runs bundled read-only utility scripts through `mf script-pack`, including
   `code/outline` for source symbol maps, `code/dependency-graph` for bounded relative import graphs,
+  `code/module-boundary` for configured import-boundary guardrails,
   `code/change-impact` for git-diff impact and verification hints, `code/symbol-read` for focused source snippets,
   `code/route-outline` for Hono, Elysia, Axum, and NestJS route maps, `docs/reference-drift` for stale
   documentation references, `repo/config-chain` for nearby config inheritance,
@@ -296,6 +297,7 @@ mf run mustflow_update_apply
 | `mf script-pack suggest --path <path> --phase before_change` | Rank helpers for an explicit path and workflow phase before deciding which script to run. |
 | `mf script-pack run code/outline scan <path...> --json` | Scan supported source files for symbol headers, line ranges, source anchors, return metadata, and content hashes. |
 | `mf script-pack run code/dependency-graph scan <path...> --json` | Trace bounded relative import, export, require, and dynamic import edges for TypeScript and JavaScript source files. |
+| `mf script-pack run code/module-boundary check <path...> --json` | Check configured module-boundary import rules, import cycles, public entrypoints, feature imports, and shared budgets. |
 | `mf script-pack run code/change-impact analyze --base HEAD --json` | Analyze changed files and return bounded impact candidates, script-pack hints, and verification intent hints. |
 | `mf script-pack run code/symbol-read read <path> --start-line <line> --json` | Read the focused symbol range or bounded source snippet after `code/outline` identifies the relevant location. |
 | `mf script-pack run code/symbol-read read --anchor <id> --json` | Read the conservative target symbol for a structured `mf:anchor` source marker. |

package/dist/cli/commands/run/args.js

@@ -0,0 +1,83 @@
+import { renderHelp } from '../../lib/cli-output.js';
+import { t } from '../../lib/i18n.js';
+import { getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../../lib/option-parser.js';
+import { ALLOW_UNTRUSTED_ROOT_OPTION } from '../../lib/run-root-trust.js';
+const DEFAULT_ACTIVE_LOCK_WAIT_TIMEOUT_SECONDS = 300;
+const RUN_OPTIONS = [
+    { name: '--json', kind: 'boolean' },
+    { name: '--dry-run', kind: 'boolean' },
+    { name: '--plan-only', kind: 'boolean' },
+    { name: '--wait', kind: 'boolean' },
+    { name: ALLOW_UNTRUSTED_ROOT_OPTION, kind: 'boolean' },
+    { name: '--wait-timeout', kind: 'string' },
+];
+export function hasRunHelpOption(args) {
+    return hasCliOptionToken(args, '--help', ['-h']);
+}
+export function parseRunArguments(args) {
+    const parsed = parseCliOptions(args, RUN_OPTIONS, { allowPositionals: true });
+    let waitTimeoutSeconds = DEFAULT_ACTIVE_LOCK_WAIT_TIMEOUT_SECONDS;
+    if (parsed.error) {
+        const [intentName, ...extra] = parsed.positionals;
+        return {
+            json: hasParsedCliOption(parsed, '--json'),
+            dryRun: hasParsedCliOption(parsed, '--dry-run'),
+            planOnly: hasParsedCliOption(parsed, '--plan-only'),
+            allowUntrustedRoot: hasParsedCliOption(parsed, ALLOW_UNTRUSTED_ROOT_OPTION),
+            wait: hasParsedCliOption(parsed, '--wait'),
+            waitTimeoutSeconds,
+            intentName: intentName ?? null,
+            extra,
+            error: parsed.error,
+        };
+    }
+    const waitTimeoutValue = getParsedCliStringOption(parsed, '--wait-timeout');
+    let error = null;
+    if (waitTimeoutValue !== null) {
+        const parsedWaitTimeout = Number(waitTimeoutValue);
+        if (!Number.isInteger(parsedWaitTimeout) || parsedWaitTimeout <= 0) {
+            error = 'invalid_wait_timeout';
+        }
+        else {
+            waitTimeoutSeconds = parsedWaitTimeout;
+        }
+    }
+    const [intentName, ...extra] = parsed.positionals;
+    return {
+        json: hasParsedCliOption(parsed, '--json'),
+        dryRun: hasParsedCliOption(parsed, '--dry-run'),
+        planOnly: hasParsedCliOption(parsed, '--plan-only'),
+        allowUntrustedRoot: hasParsedCliOption(parsed, ALLOW_UNTRUSTED_ROOT_OPTION),
+        wait: hasParsedCliOption(parsed, '--wait'),
+        waitTimeoutSeconds,
+        intentName: intentName ?? null,
+        extra,
+        error,
+    };
+}
+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: '--wait', description: t(lang, 'run.help.option.wait') },
+            { label: '--wait-timeout <seconds>', description: t(lang, 'run.help.option.waitTimeout') },
+            { label: ALLOW_UNTRUSTED_ROOT_OPTION, description: t(lang, 'run.help.option.allowUntrustedRoot') },
+            { label: '-h, --help', description: t(lang, 'cli.option.help') },
+        ],
+        examples: ['mf run test', 'mf run lint --json', 'mf run mustflow_check --dry-run --json'],
+        exitCodes: [
+            {
+                label: '0',
+                description: t(lang, 'run.help.exit.ok'),
+            },
+            {
+                label: '1',
+                description: t(lang, 'run.help.exit.fail'),
+            },
+        ],
+    }, lang);
+}

package/dist/cli/commands/run/execution.js

@@ -0,0 +1,334 @@
+import { createHash } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { ACTIVE_RUN_LOCK_ID_ENV, acquireActiveRunLock } from '../../../core/active-run-locks.js';
+import { createCommandEnv } from '../../../core/command-env.js';
+import { readCommandContract, readMustflowConfigIfExists } from '../../../core/config-loading.js';
+import { createCorrelationId } from '../../../core/correlation-id.js';
+import { recordRunPerformanceHistory } from '../../../core/run-performance-history.js';
+import { RunProfiler } from '../../../core/run-profile.js';
+import { writeRunReceipt, } from '../../../core/run-receipt.js';
+import { finishRunWriteTracking, startRunWriteTracking } from '../../../core/run-write-drift.js';
+import { resolveRunReceiptRetentionPolicy } from '../../../core/retention-policy.js';
+import { renderCliError } from '../../lib/cli-output.js';
+import { t } from '../../lib/i18n.js';
+import { resolveMustflowRoot } from '../../lib/project-root.js';
+import { assessRunRootTrust } from '../../lib/run-root-trust.js';
+import { createRunPlan, createRunPreview, } from '../../lib/run-plan.js';
+import { getRunStatus, runArgvCommandStreaming, runShellCommandStreaming } from './executor.js';
+import { emitOutput, isOutputLimitExceededError } from './output.js';
+import { createPendingTimeoutTermination, getKillMethod, terminateProcessTree } from './process-tree.js';
+import { writeLatestRunProfile } from './profile.js';
+import { assembleRunReceipt } from './receipt.js';
+const ACTIVE_LOCK_WAIT_POLL_MS = 1_000;
+function delay(milliseconds) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, milliseconds);
+    });
+}
+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 'agent_shell_requires_allow':
+            message = t(lang, 'run.error.agentShellRequiresAllow', { 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 'blocked_long_running_command_pattern':
+            message = t(lang, 'run.error.blockedLongRunningCommand', {
+                intent: plan.intentName,
+                detail: getRunPlanDetail(plan, lang, 'run.error.blockedLongRunningCommandDetail'),
+            });
+            break;
+        case 'network_requires_approval':
+        case 'destructive_requires_approval':
+        case 'approval_policy_unreadable':
+            message = t(lang, 'run.error.approvalRequired', {
+                intent: plan.intentName,
+                detail: getRunPlanDetail(plan, lang, 'run.error.approvalRequiredDetail'),
+            });
+            break;
+        case 'cwd_outside_project':
+            message = t(lang, 'run.error.cwdOutsideProject', {
+                intent: plan.intentName,
+                detail: getRunPlanDetail(plan, lang, 'run.error.cwdOutsideProjectDetail'),
+            });
+            break;
+        case 'invalid_test_target':
+            message = t(lang, 'run.error.invalidTestTarget', {
+                intent: plan.intentName,
+                detail: getRunPlanDetail(plan, lang, 'run.error.invalidTestTargetDetail'),
+            });
+            break;
+        case 'max_output_bytes_exceeds_limit':
+            message = t(lang, 'run.error.maxOutputBytes', {
+                intent: plan.intentName,
+                detail: getRunPlanDetail(plan, lang, 'run.error.maxOutputBytesDetail'),
+            });
+            break;
+        case 'intent_not_table':
+        default:
+            message = t(lang, 'run.error.unknownIntent', { intent: plan.intentName });
+            break;
+    }
+    if (plan.suggestedIntentSnippet) {
+        message = `${message}\n\n${t(lang, 'run.label.suggestedIntentSnippet')}:\n${plan.suggestedIntentSnippet}`;
+    }
+    reporter.stderr(renderCliError(message, 'mf help commands', lang));
+}
+function createPlanCommandHash(plan) {
+    const payload = {
+        mode: plan.mode,
+        cwd: plan.relativeCwd,
+        argv: plan.commandArgv ?? null,
+        cmd: plan.shellCommand ?? null,
+    };
+    return `sha256:${createHash('sha256').update(JSON.stringify(payload)).digest('hex')}`;
+}
+function renderActiveLockConflictMessage(intentName, conflicts, lang) {
+    const [first] = conflicts;
+    const detail = first
+        ? t(lang, 'run.error.activeLockConflictDetail', {
+            lock: first.lock,
+            intent: first.conflictsWithIntent,
+            pid: first.conflictsWithPid,
+        })
+        : t(lang, 'run.error.activeLockConflictUnknown');
+    return t(lang, 'run.error.activeLockConflict', { intent: intentName, detail });
+}
+async function acquireActiveRunLockWithOptionalWait(input) {
+    const startedAt = Date.now();
+    let reportedWait = false;
+    while (true) {
+        const result = acquireActiveRunLock(input.projectRoot, input.contract, input.intentName, { commandHash: input.commandHash });
+        if (result.ok || !input.enabled || result.conflicts.length === 0) {
+            return result;
+        }
+        if (!input.json && !reportedWait) {
+            const [first] = result.conflicts;
+            input.reporter.stderr(t(input.lang, 'run.progress.waitingForActiveLock', {
+                intent: input.intentName,
+                activeIntent: first?.conflictsWithIntent ?? 'unknown',
+                seconds: input.waitTimeoutSeconds,
+            }));
+            reportedWait = true;
+        }
+        if (Date.now() - startedAt >= input.waitTimeoutSeconds * 1000) {
+            return result;
+        }
+        await delay(Math.min(ACTIVE_LOCK_WAIT_POLL_MS, Math.max(1, input.waitTimeoutSeconds * 1000 - (Date.now() - startedAt))));
+    }
+}
+function createRunProgressReporter(input) {
+    if (!input.enabled) {
+        return () => undefined;
+    }
+    input.reporter.stderr(t(input.lang, 'run.progress.started', { intent: input.intentName, seconds: input.timeoutSeconds }));
+    const timers = [];
+    for (const ratio of [0.5, 0.8]) {
+        const delayMs = Math.max(1, Math.floor(input.timeoutSeconds * 1000 * ratio));
+        const elapsedSeconds = Math.max(1, Math.round(input.timeoutSeconds * ratio));
+        const timer = setTimeout(() => {
+            input.reporter.stderr(t(input.lang, 'run.progress.timeoutWarning', {
+                intent: input.intentName,
+                seconds: elapsedSeconds,
+                percent: Math.round(ratio * 100),
+            }));
+        }, delayMs);
+        timer.unref?.();
+        timers.push(timer);
+    }
+    return () => {
+        for (const timer of timers) {
+            clearTimeout(timer);
+        }
+    };
+}
+export async function executeRunCommand(request, reporter, lang = 'en', options = {}) {
+    const executorStartedAtMs = performance.now();
+    const profiler = new RunProfiler();
+    const projectRoot = profiler.measure('root_detection', () => resolveMustflowRoot());
+    const rootTrust = profiler.measure('root_trust', () => assessRunRootTrust(projectRoot));
+    const jsonLikeOutput = request.outputMode !== 'text';
+    if (!request.allowUntrustedRoot && !rootTrust.trusted) {
+        const message = rootTrust.reason === 'manifest_lock_invalid'
+            ? t(lang, 'run.error.untrustedRootInvalid', { detail: rootTrust.detail ?? rootTrust.manifestLockPath })
+            : t(lang, 'run.error.untrustedRootMissing', { path: rootTrust.detail ?? rootTrust.manifestLockPath });
+        reporter.stderr(renderCliError(message, 'mf run --help', lang));
+        return { exitCode: 1, receipt: null };
+    }
+    const contract = profiler.measure('command_contract', () => readCommandContract(projectRoot));
+    const plan = profiler.measure('plan_creation', () => createRunPlan(projectRoot, contract, request.intentName, { testTargets: options.testTargets }));
+    if (!plan.ok) {
+        if (request.outputMode === 'json') {
+            reporter.stdout(JSON.stringify(createRunPreview(plan, 'plan-only'), null, 2));
+        }
+        reportRunPlanFailure(plan, reporter, lang);
+        writeLatestRunProfile(profiler, options, {
+            projectRoot,
+            intent: request.intentName,
+            status: 'blocked',
+            previewMode: null,
+        });
+        return { exitCode: 1, receipt: null };
+    }
+    const activeRunLock = await profiler.measureAsync('active_lock_acquire', () => acquireActiveRunLockWithOptionalWait({
+        enabled: request.wait,
+        waitTimeoutSeconds: request.waitTimeoutSeconds,
+        projectRoot,
+        contract,
+        intentName: request.intentName,
+        commandHash: createPlanCommandHash(plan),
+        json: jsonLikeOutput,
+        reporter,
+        lang,
+    }));
+    if (!activeRunLock.ok) {
+        reporter.stderr(renderCliError(renderActiveLockConflictMessage(request.intentName, activeRunLock.conflicts, lang), 'mf run --dry-run --json', lang));
+        writeLatestRunProfile(profiler, options, {
+            projectRoot,
+            intent: request.intentName,
+            status: 'blocked',
+            previewMode: null,
+        });
+        return { exitCode: 1, receipt: null };
+    }
+    try {
+        const runReceiptPolicy = profiler.measure('retention_policy', () => resolveRunReceiptRetentionPolicy(readMustflowConfigIfExists(projectRoot)));
+        const env = profiler.measure('environment', () => createCommandEnv(projectRoot, { policy: plan.envPolicy, allowlist: plan.envAllowlist }));
+        env[ACTIVE_RUN_LOCK_ID_ENV] = activeRunLock.handle.record.run_id;
+        const writeTracker = profiler.measure('write_drift_before', () => startRunWriteTracking(projectRoot, contract, request.intentName, {
+            additionalDeclaredPaths: options.additionalDeclaredWritePaths,
+            env,
+        }));
+        const stdoutTailBytes = Math.min(runReceiptPolicy.stdoutTailBytes, plan.maxOutputBytes);
+        const stderrTailBytes = Math.min(runReceiptPolicy.stderrTailBytes, plan.maxOutputBytes);
+        let streamedOutput = false;
+        const childStartedAtMs = performance.now();
+        const startedAt = new Date();
+        const streamChildOutput = request.outputMode === 'text';
+        const stopRunProgress = createRunProgressReporter({
+            enabled: streamChildOutput && Boolean(reporter.writeStderr),
+            intentName: request.intentName,
+            timeoutSeconds: plan.timeoutSeconds,
+            reporter,
+            lang,
+        });
+        const result = await profiler.measureAsync('child_command', async () => {
+            try {
+                if (plan.commandArgv) {
+                    streamedOutput = streamChildOutput;
+                    return runArgvCommandStreaming(plan.argvCommand, plan.cwd, env, plan.timeoutSeconds, plan.killAfterSeconds, plan.maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamChildOutput, true);
+                }
+                streamedOutput = streamChildOutput;
+                return runShellCommandStreaming(plan.shellCommand, plan.cwd, env, plan.timeoutSeconds, plan.killAfterSeconds, plan.maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamChildOutput, true);
+            }
+            finally {
+                stopRunProgress();
+            }
+        });
+        const childDurationMs = performance.now() - childStartedAtMs;
+        const finishedAt = new Date();
+        const writeDrift = profiler.measure('write_drift_after', () => finishRunWriteTracking(writeTracker));
+        const exitCode = typeof result.status === 'number' ? result.status : null;
+        const runStatus = getRunStatus(result.error, exitCode, plan.successExitCodes);
+        let killMethod = null;
+        let termination = null;
+        if (runStatus === 'timed_out') {
+            termination = result.termination ?? createPendingTimeoutTermination(getKillMethod());
+            killMethod = termination.method;
+            if (!result.termination && result.pid) {
+                terminateProcessTree(result.pid);
+            }
+        }
+        const receipt = profiler.measure('receipt_create', () => assembleRunReceipt({
+            correlationId: options.correlationId ?? createCorrelationId('run'),
+            intentName: request.intentName,
+            runStatus,
+            startedAt,
+            finishedAt,
+            projectRoot,
+            plan,
+            result,
+            exitCode,
+            killMethod,
+            termination,
+            writeDrift,
+            executorOverheadMs: Math.max(0, Math.round((performance.now() - executorStartedAtMs - childDurationMs) * 1000) / 1000),
+            phaseTimings: profiler.getReceiptPhases(),
+            stdoutTailBytes: runReceiptPolicy.stdoutTailBytes,
+            stderrTailBytes: runReceiptPolicy.stderrTailBytes,
+        }));
+        if (options.writeLatestReceipt !== false) {
+            profiler.measure('receipt_write', () => writeRunReceipt(projectRoot, receipt));
+        }
+        if (options.recordPerformanceHistory !== false) {
+            profiler.measure('performance_history_write', () => recordRunPerformanceHistory(projectRoot, receipt));
+        }
+        writeLatestRunProfile(profiler, options, {
+            projectRoot,
+            intent: request.intentName,
+            status: runStatus,
+            previewMode: null,
+        });
+        const commandExitCode = runStatus === 'passed' ? 0 : 1;
+        if (request.outputMode === 'json') {
+            reporter.stdout(JSON.stringify(receipt, null, 2));
+            return { exitCode: commandExitCode, receipt };
+        }
+        if (request.outputMode === 'silent') {
+            return { exitCode: commandExitCode, receipt };
+        }
+        if (!streamedOutput) {
+            emitOutput(reporter, result.stdout, 'stdout');
+            emitOutput(reporter, result.stderr, 'stderr');
+        }
+        if (result.error) {
+            const errorWithCode = result.error;
+            if (errorWithCode.code === 'ETIMEDOUT') {
+                reporter.stderr(t(lang, 'run.error.timedOut', { intent: request.intentName, seconds: plan.timeoutSeconds }));
+                return { exitCode: 1, receipt };
+            }
+            if (isOutputLimitExceededError(result.error)) {
+                reporter.stderr(t(lang, 'run.error.outputLimitExceeded', { intent: request.intentName, message: result.error.message }));
+                return { exitCode: 1, receipt };
+            }
+            reporter.stderr(t(lang, 'run.error.startFailed', { intent: request.intentName, message: result.error.message }));
+            return { exitCode: 1, receipt };
+        }
+        return { exitCode: commandExitCode, receipt };
+    }
+    finally {
+        activeRunLock.handle.release();
+    }
+}

package/dist/cli/commands/run/preview.js

@@ -0,0 +1,29 @@
+import { readCommandContract } from '../../../core/config-loading.js';
+import { RunProfiler } from '../../../core/run-profile.js';
+import { resolveMustflowRoot } from '../../lib/project-root.js';
+import { createRunPlan, createRunPreview, renderRunPreviewText, } from '../../lib/run-plan.js';
+import { writeLatestRunProfile } from './profile.js';
+export function getRunPreviewMode(input) {
+    return input.dryRun ? 'dry-run' : input.planOnly ? 'plan-only' : null;
+}
+export function executeRunPreviewCommand(input, reporter, lang, options) {
+    const profiler = new RunProfiler();
+    const projectRoot = profiler.measure('root_detection', () => resolveMustflowRoot());
+    const contract = profiler.measure('command_contract', () => readCommandContract(projectRoot));
+    const plan = profiler.measure('plan_creation', () => createRunPlan(projectRoot, contract, input.intentName, { testTargets: options.testTargets }));
+    profiler.measure('preview_render', () => {
+        if (input.json) {
+            reporter.stdout(JSON.stringify(createRunPreview(plan, input.previewMode), null, 2));
+        }
+        else {
+            reporter.stdout(renderRunPreviewText(plan, input.previewMode, lang));
+        }
+    });
+    writeLatestRunProfile(profiler, options, {
+        projectRoot,
+        intent: input.intentName,
+        status: plan.ok ? 'previewed' : 'blocked',
+        previewMode: input.previewMode,
+    });
+    return plan.ok ? 0 : 1;
+}

package/dist/cli/commands/run/profile.js

@@ -0,0 +1,6 @@
+export function writeLatestRunProfile(profiler, options, input) {
+    if (options.writeLatestProfile === false) {
+        return;
+    }
+    profiler.writeLatest(input);
+}