mustflow 2.75.2 → 2.85.4

package/dist/cli/script-packs/docs-reference-drift.js

@@ -0,0 +1,150 @@
+import { printUsageError, renderHelp } from '../lib/cli-output.js';
+import { COMMAND_DEFINITIONS } from '../lib/command-registry.js';
+import { t } from '../lib/i18n.js';
+import { formatCliOptionParseError, getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
+import { resolveMustflowRoot } from '../lib/project-root.js';
+import { listScriptPackScripts } from '../lib/script-pack-registry.js';
+import { checkReferenceDrift, REFERENCE_DRIFT_SCRIPT_REF, } from '../../core/reference-drift.js';
+import { getPublicJsonSchemaFiles } from '../../core/public-json-contracts.js';
+const REFERENCE_DRIFT_OPTIONS = [
+    { name: '--json', kind: 'boolean' },
+    { name: '--max-files', kind: 'string' },
+    { name: '--max-file-bytes', kind: 'string' },
+];
+function parsePositiveInteger(value, option, lang) {
+    if (value === null) {
+        return { value: null };
+    }
+    if (!/^[1-9]\d*$/u.test(value)) {
+        return { value: null, error: t(lang, 'referenceDrift.error.invalidPositiveInteger', { option, value }) };
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed)) {
+        return { value: null, error: t(lang, 'referenceDrift.error.invalidPositiveInteger', { option, value }) };
+    }
+    return { value: parsed };
+}
+export function getDocsReferenceDriftHelp(lang = 'en') {
+    return renderHelp({
+        usage: 'mf script-pack run docs/reference-drift check [path...] [options]',
+        summary: t(lang, 'referenceDrift.help.summary'),
+        options: [
+            { label: '--max-files <count>', description: t(lang, 'referenceDrift.help.option.maxFiles') },
+            { label: '--max-file-bytes <bytes>', description: t(lang, 'referenceDrift.help.option.maxFileBytes') },
+            { label: '--json', description: t(lang, 'cli.option.json') },
+            { label: '-h, --help', description: t(lang, 'cli.option.help') },
+        ],
+        examples: [
+            'mf script-pack run docs/reference-drift check --json',
+            'mf script-pack run docs/reference-drift check README.md schemas/README.md --json',
+            'mf script-pack run docs/reference-drift check docs-site/src/content/docs --max-files 80 --json',
+        ],
+        exitCodes: [
+            { label: '0', description: t(lang, 'referenceDrift.help.exit.ok') },
+            { label: '1', description: t(lang, 'referenceDrift.help.exit.fail') },
+        ],
+    }, lang);
+}
+function parseReferenceDriftOptions(args, lang) {
+    const [action, ...rest] = args;
+    const parsed = parseCliOptions(rest, REFERENCE_DRIFT_OPTIONS, { allowPositionals: true });
+    const json = hasParsedCliOption(parsed, '--json');
+    const maxFiles = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-files'), '--max-files', lang);
+    const maxFileBytes = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-file-bytes'), '--max-file-bytes', lang);
+    if (action !== 'check') {
+        return {
+            action: 'check',
+            json,
+            paths: parsed.positionals,
+            maxFiles: maxFiles.value,
+            maxFileBytes: maxFileBytes.value,
+            error: action
+                ? t(lang, 'referenceDrift.error.unknownAction', { action })
+                : t(lang, 'referenceDrift.error.missingAction'),
+        };
+    }
+    if (parsed.error) {
+        return {
+            action,
+            json,
+            paths: parsed.positionals,
+            maxFiles: maxFiles.value,
+            maxFileBytes: maxFileBytes.value,
+            error: formatCliOptionParseError(parsed.error, lang),
+        };
+    }
+    for (const candidate of [maxFiles, maxFileBytes]) {
+        if (candidate.error) {
+            return {
+                action,
+                json,
+                paths: parsed.positionals,
+                maxFiles: maxFiles.value,
+                maxFileBytes: maxFileBytes.value,
+                error: candidate.error,
+            };
+        }
+    }
+    return {
+        action,
+        json,
+        paths: parsed.positionals,
+        maxFiles: maxFiles.value,
+        maxFileBytes: maxFileBytes.value,
+    };
+}
+function renderReferenceDriftSummary(report, lang) {
+    const lines = [
+        t(lang, 'referenceDrift.title'),
+        `${t(lang, 'scriptPack.label.script')}: ${REFERENCE_DRIFT_SCRIPT_REF}`,
+        `${t(lang, 'label.status')}: ${report.status}`,
+        `${t(lang, 'referenceDrift.label.files')}: ${report.files.length}`,
+        `${t(lang, 'referenceDrift.label.references')}: ${report.references.length}`,
+        `${t(lang, 'referenceDrift.label.findings')}: ${report.findings.length}`,
+    ];
+    if (report.references.length > 0) {
+        lines.push(t(lang, 'referenceDrift.label.references'));
+        for (const reference of report.references.slice(0, 40)) {
+            lines.push(`- ${reference.path}:${reference.line}: ${reference.kind} ${reference.target} (${reference.status})`);
+        }
+    }
+    if (report.findings.length > 0) {
+        lines.push(t(lang, 'referenceDrift.label.findings'));
+        for (const finding of report.findings) {
+            const line = finding.line === undefined ? '' : `:${finding.line}`;
+            lines.push(`- ${finding.path}${line}: ${finding.code} (${finding.message})`);
+        }
+    }
+    if (report.issues.length > 0) {
+        lines.push(t(lang, 'referenceDrift.label.issues'), ...report.issues.map((issue) => `- ${issue}`));
+    }
+    if (report.references.length === 0 && report.findings.length === 0 && report.issues.length === 0) {
+        lines.push(t(lang, 'referenceDrift.clean'));
+    }
+    return lines.join('\n');
+}
+export function runDocsReferenceDriftScript(args, reporter, lang = 'en') {
+    if (hasCliOptionToken(args, '--help', ['-h'])) {
+        reporter.stdout(getDocsReferenceDriftHelp(lang));
+        return 0;
+    }
+    const options = parseReferenceDriftOptions(args, lang);
+    if (options.error) {
+        printUsageError(reporter, options.error, 'mf script-pack run docs/reference-drift --help', getDocsReferenceDriftHelp(lang), lang);
+        return 1;
+    }
+    const report = checkReferenceDrift(resolveMustflowRoot(), {
+        paths: options.paths,
+        commandNames: COMMAND_DEFINITIONS.map((definition) => definition.id),
+        scriptRefs: listScriptPackScripts().map((script) => script.ref),
+        schemaFiles: getPublicJsonSchemaFiles(),
+        maxFiles: options.maxFiles ?? undefined,
+        maxFileBytes: options.maxFileBytes ?? undefined,
+    });
+    if (options.json) {
+        reporter.stdout(JSON.stringify(report, null, 2));
+        return report.ok ? 0 : 1;
+    }
+    reporter.stdout(renderReferenceDriftSummary(report, lang));
+    return report.ok ? 0 : 1;
+}

package/dist/cli/script-packs/repo-config-chain.js

@@ -0,0 +1,163 @@
+import { printUsageError, renderHelp } from '../lib/cli-output.js';
+import { t } from '../lib/i18n.js';
+import { formatCliOptionParseError, getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
+import { resolveMustflowRoot } from '../lib/project-root.js';
+import { CONFIG_CHAIN_SCRIPT_REF, inspectConfigChain, } from '../../core/config-chain.js';
+const CONFIG_CHAIN_OPTIONS = [
+    { name: '--json', kind: 'boolean' },
+    { name: '--max-configs', kind: 'string' },
+    { name: '--max-file-bytes', kind: 'string' },
+];
+function parsePositiveInteger(value, option, lang) {
+    if (value === null) {
+        return { value: null };
+    }
+    if (!/^[1-9]\d*$/u.test(value)) {
+        return { value: null, error: t(lang, 'configChain.error.invalidPositiveInteger', { option, value }) };
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed)) {
+        return { value: null, error: t(lang, 'configChain.error.invalidPositiveInteger', { option, value }) };
+    }
+    return { value: parsed };
+}
+export function getRepoConfigChainHelp(lang = 'en') {
+    return renderHelp({
+        usage: 'mf script-pack run repo/config-chain inspect <path...> [options]',
+        summary: t(lang, 'configChain.help.summary'),
+        options: [
+            { label: '--max-configs <count>', description: t(lang, 'configChain.help.option.maxConfigs') },
+            { label: '--max-file-bytes <bytes>', description: t(lang, 'configChain.help.option.maxFileBytes') },
+            { label: '--json', description: t(lang, 'cli.option.json') },
+            { label: '-h, --help', description: t(lang, 'cli.option.help') },
+        ],
+        examples: [
+            'mf script-pack run repo/config-chain inspect src --json',
+            'mf script-pack run repo/config-chain inspect tsconfig.json src/index.ts --json',
+            'mf script-pack run repo/config-chain inspect . --max-configs 40 --json',
+        ],
+        exitCodes: [
+            { label: '0', description: t(lang, 'configChain.help.exit.ok') },
+            { label: '1', description: t(lang, 'configChain.help.exit.fail') },
+        ],
+    }, lang);
+}
+function parseConfigChainOptions(args, lang) {
+    const [action, ...rest] = args;
+    const parsed = parseCliOptions(rest, CONFIG_CHAIN_OPTIONS, { allowPositionals: true });
+    const json = hasParsedCliOption(parsed, '--json');
+    const maxConfigs = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-configs'), '--max-configs', lang);
+    const maxFileBytes = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-file-bytes'), '--max-file-bytes', lang);
+    if (action !== 'inspect') {
+        return {
+            action: 'inspect',
+            json,
+            paths: parsed.positionals,
+            maxConfigs: maxConfigs.value,
+            maxFileBytes: maxFileBytes.value,
+            error: action ? t(lang, 'configChain.error.unknownAction', { action }) : t(lang, 'configChain.error.missingAction'),
+        };
+    }
+    if (parsed.error) {
+        return {
+            action,
+            json,
+            paths: parsed.positionals,
+            maxConfigs: maxConfigs.value,
+            maxFileBytes: maxFileBytes.value,
+            error: formatCliOptionParseError(parsed.error, lang),
+        };
+    }
+    for (const candidate of [maxConfigs, maxFileBytes]) {
+        if (candidate.error) {
+            return {
+                action,
+                json,
+                paths: parsed.positionals,
+                maxConfigs: maxConfigs.value,
+                maxFileBytes: maxFileBytes.value,
+                error: candidate.error,
+            };
+        }
+    }
+    if (parsed.positionals.length === 0) {
+        return {
+            action,
+            json,
+            paths: parsed.positionals,
+            maxConfigs: maxConfigs.value,
+            maxFileBytes: maxFileBytes.value,
+            error: t(lang, 'configChain.error.missingPath'),
+        };
+    }
+    return {
+        action,
+        json,
+        paths: parsed.positionals,
+        maxConfigs: maxConfigs.value,
+        maxFileBytes: maxFileBytes.value,
+    };
+}
+function renderConfigChainSummary(report, lang) {
+    const lines = [
+        t(lang, 'configChain.title'),
+        `${t(lang, 'scriptPack.label.script')}: ${CONFIG_CHAIN_SCRIPT_REF}`,
+        `${t(lang, 'label.status')}: ${report.status}`,
+        `${t(lang, 'configChain.label.targets')}: ${report.targets.length}`,
+        `${t(lang, 'configChain.label.configs')}: ${report.configs.length}`,
+        `${t(lang, 'configChain.label.edges')}: ${report.edges.length}`,
+        `${t(lang, 'configChain.label.findings')}: ${report.findings.length}`,
+    ];
+    if (report.configs.length > 0) {
+        lines.push(t(lang, 'configChain.label.configs'));
+        for (const config of report.configs) {
+            const dynamic = config.dynamic ? `, ${t(lang, 'configChain.label.dynamic')}` : '';
+            lines.push(`- ${config.path}: ${config.kind}, ${config.format}${dynamic}`);
+            for (const summary of config.summary.slice(0, 4)) {
+                lines.push(`  - ${summary}`);
+            }
+        }
+    }
+    if (report.edges.length > 0) {
+        lines.push(t(lang, 'configChain.label.edges'));
+        for (const edge of report.edges) {
+            const target = edge.to_path ?? edge.specifier;
+            lines.push(`- ${edge.from_path} -> ${target}: ${edge.kind}`);
+        }
+    }
+    if (report.findings.length > 0) {
+        lines.push(t(lang, 'configChain.label.findings'));
+        for (const finding of report.findings) {
+            lines.push(`- ${finding.path}: ${finding.code} (${finding.message})`);
+        }
+    }
+    if (report.issues.length > 0) {
+        lines.push(t(lang, 'configChain.label.issues'), ...report.issues.map((issue) => `- ${issue}`));
+    }
+    if (report.configs.length === 0 && report.findings.length === 0 && report.issues.length === 0) {
+        lines.push(t(lang, 'configChain.clean'));
+    }
+    return lines.join('\n');
+}
+export function runRepoConfigChainScript(args, reporter, lang = 'en') {
+    if (hasCliOptionToken(args, '--help', ['-h'])) {
+        reporter.stdout(getRepoConfigChainHelp(lang));
+        return 0;
+    }
+    const options = parseConfigChainOptions(args, lang);
+    if (options.error) {
+        printUsageError(reporter, options.error, 'mf script-pack run repo/config-chain --help', getRepoConfigChainHelp(lang), lang);
+        return 1;
+    }
+    const report = inspectConfigChain(resolveMustflowRoot(), {
+        paths: options.paths,
+        maxConfigs: options.maxConfigs ?? undefined,
+        maxFileBytes: options.maxFileBytes ?? undefined,
+    });
+    if (options.json) {
+        reporter.stdout(JSON.stringify(report, null, 2));
+        return report.ok ? 0 : 1;
+    }
+    reporter.stdout(renderConfigChainSummary(report, lang));
+    return report.ok ? 0 : 1;
+}

package/dist/cli/script-packs/repo-env-contract.js

@@ -0,0 +1,156 @@
+import { printUsageError, renderHelp } from '../lib/cli-output.js';
+import { t } from '../lib/i18n.js';
+import { formatCliOptionParseError, getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
+import { resolveMustflowRoot } from '../lib/project-root.js';
+import { ENV_CONTRACT_SCRIPT_REF, inspectEnvContract } from '../../core/env-contract.js';
+const ENV_CONTRACT_OPTIONS = [
+    { name: '--json', kind: 'boolean' },
+    { name: '--max-files', kind: 'string' },
+    { name: '--max-file-bytes', kind: 'string' },
+    { name: '--max-keys', kind: 'string' },
+];
+function parsePositiveInteger(value, option, lang) {
+    if (value === null) {
+        return { value: null };
+    }
+    if (!/^[1-9]\d*$/u.test(value)) {
+        return { value: null, error: t(lang, 'envContract.error.invalidPositiveInteger', { option, value }) };
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed)) {
+        return { value: null, error: t(lang, 'envContract.error.invalidPositiveInteger', { option, value }) };
+    }
+    return { value: parsed };
+}
+export function getRepoEnvContractHelp(lang = 'en') {
+    return renderHelp({
+        usage: 'mf script-pack run repo/env-contract scan [path...] [options]',
+        summary: t(lang, 'envContract.help.summary'),
+        options: [
+            { label: '--max-files <count>', description: t(lang, 'envContract.help.option.maxFiles') },
+            { label: '--max-file-bytes <bytes>', description: t(lang, 'envContract.help.option.maxFileBytes') },
+            { label: '--max-keys <count>', description: t(lang, 'envContract.help.option.maxKeys') },
+            { label: '--json', description: t(lang, 'cli.option.json') },
+            { label: '-h, --help', description: t(lang, 'cli.option.help') },
+        ],
+        examples: [
+            'mf script-pack run repo/env-contract scan --json',
+            'mf script-pack run repo/env-contract scan src .env.example --json',
+            'mf script-pack run repo/env-contract scan .github/workflows README.md --max-keys 120 --json',
+        ],
+        exitCodes: [
+            { label: '0', description: t(lang, 'envContract.help.exit.ok') },
+            { label: '1', description: t(lang, 'envContract.help.exit.fail') },
+        ],
+    }, lang);
+}
+function parseEnvContractOptions(args, lang) {
+    const [action, ...rest] = args;
+    const parsed = parseCliOptions(rest, ENV_CONTRACT_OPTIONS, { allowPositionals: true });
+    const json = hasParsedCliOption(parsed, '--json');
+    const maxFiles = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-files'), '--max-files', lang);
+    const maxFileBytes = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-file-bytes'), '--max-file-bytes', lang);
+    const maxKeys = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-keys'), '--max-keys', lang);
+    if (action !== 'scan') {
+        return {
+            action: 'scan',
+            json,
+            paths: parsed.positionals,
+            maxFiles: maxFiles.value,
+            maxFileBytes: maxFileBytes.value,
+            maxKeys: maxKeys.value,
+            error: action ? t(lang, 'envContract.error.unknownAction', { action }) : t(lang, 'envContract.error.missingAction'),
+        };
+    }
+    if (parsed.error) {
+        return {
+            action,
+            json,
+            paths: parsed.positionals,
+            maxFiles: maxFiles.value,
+            maxFileBytes: maxFileBytes.value,
+            maxKeys: maxKeys.value,
+            error: formatCliOptionParseError(parsed.error, lang),
+        };
+    }
+    for (const candidate of [maxFiles, maxFileBytes, maxKeys]) {
+        if (candidate.error) {
+            return {
+                action,
+                json,
+                paths: parsed.positionals,
+                maxFiles: maxFiles.value,
+                maxFileBytes: maxFileBytes.value,
+                maxKeys: maxKeys.value,
+                error: candidate.error,
+            };
+        }
+    }
+    return {
+        action,
+        json,
+        paths: parsed.positionals,
+        maxFiles: maxFiles.value,
+        maxFileBytes: maxFileBytes.value,
+        maxKeys: maxKeys.value,
+    };
+}
+function renderEnvContractSummary(report, lang) {
+    const lines = [
+        t(lang, 'envContract.title'),
+        `${t(lang, 'scriptPack.label.script')}: ${ENV_CONTRACT_SCRIPT_REF}`,
+        `${t(lang, 'label.status')}: ${report.status}`,
+        `${t(lang, 'envContract.label.files')}: ${report.summary.file_count}`,
+        `${t(lang, 'envContract.label.keys')}: ${report.summary.key_count}`,
+        `${t(lang, 'envContract.label.findings')}: ${report.findings.length}`,
+        `${t(lang, 'envContract.label.truncated')}: ${report.truncated ? t(lang, 'value.yes') : t(lang, 'value.no')}`,
+    ];
+    for (const entry of report.keys.slice(0, 40)) {
+        const flags = [
+            entry.used_in_code ? 'code' : null,
+            entry.declared_in_example ? 'example' : null,
+            entry.documented ? 'docs' : null,
+            entry.referenced_in_ci ? 'ci' : null,
+            entry.secret_like ? 'secret-like' : null,
+            entry.public_like ? 'public-like' : null,
+        ].filter((flag) => flag !== null);
+        lines.push(`- ${entry.key}: ${flags.join(', ') || t(lang, 'value.none')} (${entry.source_count})`);
+    }
+    if (report.findings.length > 0) {
+        lines.push(t(lang, 'envContract.label.findings'));
+        for (const finding of report.findings.slice(0, 40)) {
+            const key = finding.key ? ` ${finding.key}` : '';
+            lines.push(`- ${finding.path}:${key} ${finding.code} (${finding.message})`);
+        }
+    }
+    if (report.issues.length > 0) {
+        lines.push(t(lang, 'envContract.label.issues'), ...report.issues.map((issue) => `- ${issue}`));
+    }
+    if (report.keys.length === 0 && report.findings.length === 0 && report.issues.length === 0) {
+        lines.push(t(lang, 'envContract.clean'));
+    }
+    return lines.join('\n');
+}
+export function runRepoEnvContractScript(args, reporter, lang = 'en') {
+    if (hasCliOptionToken(args, '--help', ['-h'])) {
+        reporter.stdout(getRepoEnvContractHelp(lang));
+        return 0;
+    }
+    const options = parseEnvContractOptions(args, lang);
+    if (options.error) {
+        printUsageError(reporter, options.error, 'mf script-pack run repo/env-contract --help', getRepoEnvContractHelp(lang), lang);
+        return 1;
+    }
+    const report = inspectEnvContract(resolveMustflowRoot(), {
+        paths: options.paths,
+        maxFiles: options.maxFiles ?? undefined,
+        maxFileBytes: options.maxFileBytes ?? undefined,
+        maxKeys: options.maxKeys ?? undefined,
+    });
+    if (options.json) {
+        reporter.stdout(JSON.stringify(report, null, 2));
+        return report.ok ? 0 : 1;
+    }
+    reporter.stdout(renderEnvContractSummary(report, lang));
+    return report.ok ? 0 : 1;
+}

package/dist/cli/script-packs/repo-related-files.js

@@ -0,0 +1,161 @@
+import { printUsageError, renderHelp } from '../lib/cli-output.js';
+import { t } from '../lib/i18n.js';
+import { formatCliOptionParseError, getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
+import { resolveMustflowRoot } from '../lib/project-root.js';
+import { inspectRelatedFiles, RELATED_FILES_SCRIPT_REF, } from '../../core/related-files.js';
+const RELATED_FILES_OPTIONS = [
+    { name: '--json', kind: 'boolean' },
+    { name: '--max-files', kind: 'string' },
+    { name: '--max-file-bytes', kind: 'string' },
+    { name: '--max-candidates', kind: 'string' },
+];
+function parsePositiveInteger(value, option, lang) {
+    if (value === null) {
+        return { value: null };
+    }
+    if (!/^[1-9]\d*$/u.test(value)) {
+        return { value: null, error: t(lang, 'relatedFiles.error.invalidPositiveInteger', { option, value }) };
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed)) {
+        return { value: null, error: t(lang, 'relatedFiles.error.invalidPositiveInteger', { option, value }) };
+    }
+    return { value: parsed };
+}
+export function getRepoRelatedFilesHelp(lang = 'en') {
+    return renderHelp({
+        usage: 'mf script-pack run repo/related-files map <path...> [options]',
+        summary: t(lang, 'relatedFiles.help.summary'),
+        options: [
+            { label: '--max-files <count>', description: t(lang, 'relatedFiles.help.option.maxFiles') },
+            { label: '--max-file-bytes <bytes>', description: t(lang, 'relatedFiles.help.option.maxFileBytes') },
+            { label: '--max-candidates <count>', description: t(lang, 'relatedFiles.help.option.maxCandidates') },
+            { label: '--json', description: t(lang, 'cli.option.json') },
+            { label: '-h, --help', description: t(lang, 'cli.option.help') },
+        ],
+        examples: [
+            'mf script-pack run repo/related-files map src/cli/index.ts --json',
+            'mf script-pack run repo/related-files map src/core/code-outline.ts --max-candidates 50 --json',
+            'mf script-pack run repo/related-files map src tests/cli/package.test.js --max-files 500 --json',
+        ],
+        exitCodes: [
+            { label: '0', description: t(lang, 'relatedFiles.help.exit.ok') },
+            { label: '1', description: t(lang, 'relatedFiles.help.exit.fail') },
+        ],
+    }, lang);
+}
+function parseRelatedFilesOptions(args, lang) {
+    const [action, ...rest] = args;
+    const parsed = parseCliOptions(rest, RELATED_FILES_OPTIONS, { allowPositionals: true });
+    const json = hasParsedCliOption(parsed, '--json');
+    const maxFiles = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-files'), '--max-files', lang);
+    const maxFileBytes = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-file-bytes'), '--max-file-bytes', lang);
+    const maxCandidates = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-candidates'), '--max-candidates', lang);
+    if (action !== 'map') {
+        return {
+            action: 'map',
+            json,
+            paths: parsed.positionals,
+            maxFiles: maxFiles.value,
+            maxFileBytes: maxFileBytes.value,
+            maxCandidates: maxCandidates.value,
+            error: action ? t(lang, 'relatedFiles.error.unknownAction', { action }) : t(lang, 'relatedFiles.error.missingAction'),
+        };
+    }
+    if (parsed.error) {
+        return {
+            action,
+            json,
+            paths: parsed.positionals,
+            maxFiles: maxFiles.value,
+            maxFileBytes: maxFileBytes.value,
+            maxCandidates: maxCandidates.value,
+            error: formatCliOptionParseError(parsed.error, lang),
+        };
+    }
+    for (const candidate of [maxFiles, maxFileBytes, maxCandidates]) {
+        if (candidate.error) {
+            return {
+                action,
+                json,
+                paths: parsed.positionals,
+                maxFiles: maxFiles.value,
+                maxFileBytes: maxFileBytes.value,
+                maxCandidates: maxCandidates.value,
+                error: candidate.error,
+            };
+        }
+    }
+    if (parsed.positionals.length === 0) {
+        return {
+            action,
+            json,
+            paths: parsed.positionals,
+            maxFiles: maxFiles.value,
+            maxFileBytes: maxFileBytes.value,
+            maxCandidates: maxCandidates.value,
+            error: t(lang, 'relatedFiles.error.missingPath'),
+        };
+    }
+    return {
+        action,
+        json,
+        paths: parsed.positionals,
+        maxFiles: maxFiles.value,
+        maxFileBytes: maxFileBytes.value,
+        maxCandidates: maxCandidates.value,
+    };
+}
+function renderRelatedFilesSummary(report, lang) {
+    const lines = [
+        t(lang, 'relatedFiles.title'),
+        `${t(lang, 'scriptPack.label.script')}: ${RELATED_FILES_SCRIPT_REF}`,
+        `${t(lang, 'label.status')}: ${report.status}`,
+        `${t(lang, 'relatedFiles.label.targets')}: ${report.targets.length}`,
+        `${t(lang, 'relatedFiles.label.candidates')}: ${report.candidates.length}`,
+        `${t(lang, 'relatedFiles.label.truncated')}: ${report.truncated ? t(lang, 'value.yes') : t(lang, 'value.no')}`,
+    ];
+    if (report.candidates.length > 0) {
+        lines.push(t(lang, 'relatedFiles.label.related'));
+        for (const candidate of report.candidates) {
+            const line = candidate.line === null ? '' : `:${candidate.line}`;
+            lines.push(`- ${candidate.path}: ${candidate.relationship}, ${t(lang, 'relatedFiles.label.confidence')} ${candidate.confidence} (${candidate.source_path}${line})`);
+        }
+    }
+    if (report.findings.length > 0) {
+        lines.push(t(lang, 'relatedFiles.label.findings'));
+        for (const finding of report.findings) {
+            lines.push(`- ${finding.path}: ${finding.code} (${finding.message})`);
+        }
+    }
+    if (report.issues.length > 0) {
+        lines.push(t(lang, 'relatedFiles.label.issues'), ...report.issues.map((issue) => `- ${issue}`));
+    }
+    if (report.candidates.length === 0 && report.findings.length === 0 && report.issues.length === 0) {
+        lines.push(t(lang, 'relatedFiles.clean'));
+    }
+    return lines.join('\n');
+}
+export function runRepoRelatedFilesScript(args, reporter, lang = 'en') {
+    if (hasCliOptionToken(args, '--help', ['-h'])) {
+        reporter.stdout(getRepoRelatedFilesHelp(lang));
+        return 0;
+    }
+    const options = parseRelatedFilesOptions(args, lang);
+    if (options.error) {
+        printUsageError(reporter, options.error, 'mf script-pack run repo/related-files --help', getRepoRelatedFilesHelp(lang), lang);
+        return 1;
+    }
+    const report = inspectRelatedFiles(resolveMustflowRoot(), {
+        paths: options.paths,
+        maxFiles: options.maxFiles ?? undefined,
+        maxFileBytes: options.maxFileBytes ?? undefined,
+        maxCandidates: options.maxCandidates ?? undefined,
+    });
+    if (options.json) {
+        reporter.stdout(JSON.stringify(report, null, 2));
+        return report.ok ? 0 : 1;
+    }
+    reporter.stdout(renderRelatedFilesSummary(report, lang));
+    return report.ok ? 0 : 1;
+}