mustflow 2.74.3 → 2.74.5

package/dist/cli/i18n/zh.js

@@ -40,7 +40,7 @@ export const zhMessages = {
     "command.map.summary": "生成 REPO_MAP.md",
     "command.lineEndings.summary": "检查并规范化换行符策略",
     "command.quality.summary": "Inspect changed files for quality-gaming patterns",
-    "command.scriptPack.summary": "List and run bundled mustflow script packs",
+    "command.scriptPack.summary": "List, suggest, and run bundled mustflow script packs",
     "command.run.summary": "运行已配置的一次性命令",
     "command.context.summary": "输出机器可读的代理上下文",
     "command.tech.summary": "管理代理使用的技术偏好",
@@ -749,19 +749,33 @@ export const zhMessages = {
     "quality.clean": "No quality-gaming risks found.",
     "quality.error.missingAction": "Specify a quality action: check",
     "quality.error.unknownAction": "Unknown quality action: {action}",
-    "scriptPack.help.summary": "List and run bundled mustflow script-pack utilities through one stable command namespace.",
+    "scriptPack.help.summary": "List, suggest, and run bundled mustflow script-pack utilities through one stable command namespace.",
     "scriptPack.help.exit.ok": "The script-pack command completed successfully",
     "scriptPack.help.exit.fail": "The script-pack command received invalid input or the selected script failed",
+    "scriptPack.help.option.changed": "Suggest scripts for current Git working-tree changes",
+    "scriptPack.help.option.phase": "Limit suggestions to before_change, during_change, after_change, or review",
+    "scriptPack.help.option.skill": "Prefer scripts related to a mustflow skill name",
+    "scriptPack.help.option.path": "Add a candidate path to classify for script suggestions",
     "scriptPack.title": "mustflow script packs",
+    "scriptPack.suggest.title": "mustflow script suggestions",
+    "scriptPack.suggest.label.suggestions": "Suggestions",
+    "scriptPack.suggest.label.analyzedPaths": "Analyzed paths",
+    "scriptPack.suggest.label.recommendations": "Recommendations",
+    "scriptPack.suggest.label.runHint": "Run hint",
+    "scriptPack.suggest.empty": "No script-pack suggestions matched the supplied paths, skills, or phases.",
     "scriptPack.pack.core.summary": "Core built-in utility scripts",
+    "scriptPack.pack.repo.summary": "Repository-boundary utility scripts",
     "scriptPack.script.textBudget.summary": "Check exact text length budgets for files or JSON string fields",
+    "scriptPack.script.generatedBoundary.summary": "Check whether candidate paths cross generated, ignored, protected, vendor, or cache boundaries",
     "scriptPack.label.script": "Script",
     "scriptPack.label.actions": "actions",
     "scriptPack.label.schema": "schema",
-    "scriptPack.error.missingAction": "Specify a script-pack action: list or run",
+    "scriptPack.error.missingAction": "Specify a script-pack action: list, suggest, or run",
     "scriptPack.error.unknownAction": "Unknown script-pack action: {action}",
     "scriptPack.error.missingScript": "Specify a script ref such as core/text-budget",
     "scriptPack.error.unknownScript": "Unknown script-pack script: {script}",
+    "scriptPack.error.missingSuggestInput": "Provide at least one suggestion input: --path <path>, --changed, --phase <phase>, or --skill <skill>",
+    "scriptPack.error.unknownPhase": "Unknown script-pack phase: {phase}",
     "textBudget.help.summary": "Check exact text length budgets for files or JSON string fields using grapheme counts by default.",
     "textBudget.help.option.min": "Require at least this many units",
     "textBudget.help.option.max": "Require at most this many units",
@@ -785,6 +799,19 @@ export const zhMessages = {
     "textBudget.error.invalidNumber": "{option} must be a non-negative safe integer: {value}",
     "textBudget.error.invalidUnit": "Unknown text-budget unit: {unit}. Use one of: {allowed}",
     "textBudget.error.minGreaterThanMax": "--min must be less than or equal to --max",
+    "generatedBoundary.help.summary": "Check whether candidate edit paths cross generated, ignored, protected, vendor, or cache boundaries.",
+    "generatedBoundary.help.exit.ok": "Every checked target stayed within ordinary editable project paths",
+    "generatedBoundary.help.exit.fail": "A target crossed a generated, ignored, protected, vendor, cache, or root boundary",
+    "generatedBoundary.title": "mustflow generated boundary",
+    "generatedBoundary.label.checkedTargets": "Checked targets",
+    "generatedBoundary.label.findings": "Findings",
+    "generatedBoundary.label.targets": "Targets",
+    "generatedBoundary.label.boundaries": "boundaries",
+    "generatedBoundary.label.issues": "Issues",
+    "generatedBoundary.clean": "No generated, ignored, protected, vendor, or cache boundaries matched.",
+    "generatedBoundary.error.missingAction": "Specify a generated-boundary action: check",
+    "generatedBoundary.error.unknownAction": "Unknown generated-boundary action: {action}",
+    "generatedBoundary.error.missingPath": "Provide at least one path to check",
     "run.help.summary": "从 .mustflow/config/commands.toml 运行已配置的一次性命令。",
     "run.help.option.dryRun": "输出命令计划但不执行",
     "run.help.option.planOnly": "--dry-run 的别名",

package/dist/cli/lib/script-pack-registry.js

@@ -13,11 +13,64 @@ export const SCRIPT_PACKS = [
                 usage: 'mf script-pack run core/text-budget check <path...> [options]',
                 summaryKey: 'scriptPack.script.textBudget.summary',
                 actions: ['check'],
+                useWhen: [
+                    'Check exact text budgets for docs, package metadata, prompts, release notes, or user-facing copy.',
+                    'Inspect a JSON string field by JSON Pointer when a public description, label, or summary has a length contract.',
+                ],
+                phases: ['before_change', 'after_change', 'review'],
+                readOnly: true,
+                mutates: false,
+                network: false,
+                inputs: ['path', 'json_pointer', 'budget', 'unit'],
+                outputs: ['human_summary', 'json_report'],
+                relatedSkills: [
+                    'docs-prose-review',
+                    'public-json-contract-change',
+                    'readme-authoring',
+                    'release-notes-authoring',
+                ],
+                riskLevel: 'low',
+                cost: 'low',
                 reportSchemaFile: 'text-budget-report.schema.json',
                 loadRunner: async () => (await import('../script-packs/core-text-budget.js')).runCoreTextBudgetScript,
             },
         ],
     },
+    {
+        id: 'repo',
+        summaryKey: 'scriptPack.pack.repo.summary',
+        scripts: [
+            {
+                packId: 'repo',
+                id: 'generated-boundary',
+                ref: scriptRef('repo', 'generated-boundary'),
+                usage: 'mf script-pack run repo/generated-boundary check <path...> [options]',
+                summaryKey: 'scriptPack.script.generatedBoundary.summary',
+                actions: ['check'],
+                useWhen: [
+                    'Check candidate edit paths before changing files that may be generated, ignored, protected, vendor, or cache output.',
+                    'Review changed paths after implementation when generated or protected-file drift would make completion evidence misleading.',
+                ],
+                phases: ['before_change', 'after_change', 'review'],
+                readOnly: true,
+                mutates: false,
+                network: false,
+                inputs: ['path'],
+                outputs: ['human_summary', 'json_report'],
+                relatedSkills: [
+                    'completion-evidence-gate',
+                    'proactive-risk-surfacing',
+                    'quality-gaming-guard',
+                    'repo-improvement-loop',
+                    'template-install-surface-sync',
+                ],
+                riskLevel: 'low',
+                cost: 'low',
+                reportSchemaFile: 'generated-boundary-report.schema.json',
+                loadRunner: async () => (await import('../script-packs/repo-generated-boundary.js')).runRepoGeneratedBoundaryScript,
+            },
+        ],
+    },
 ];
 export function listScriptPackScripts() {
     return SCRIPT_PACKS.flatMap((pack) => pack.scripts);

package/dist/cli/script-packs/repo-generated-boundary.js

@@ -0,0 +1,94 @@
+import { printUsageError, renderHelp } from '../lib/cli-output.js';
+import { t } from '../lib/i18n.js';
+import { formatCliOptionParseError, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
+import { resolveMustflowRoot } from '../lib/project-root.js';
+import { GENERATED_BOUNDARY_SCRIPT_REF, inspectGeneratedBoundary, } from '../../core/generated-boundary.js';
+const GENERATED_BOUNDARY_OPTIONS = [{ name: '--json', kind: 'boolean' }];
+export function getRepoGeneratedBoundaryHelp(lang = 'en') {
+    return renderHelp({
+        usage: 'mf script-pack run repo/generated-boundary check <path...> [options]',
+        summary: t(lang, 'generatedBoundary.help.summary'),
+        options: [
+            { label: '--json', description: t(lang, 'cli.option.json') },
+            { label: '-h, --help', description: t(lang, 'cli.option.help') },
+        ],
+        examples: [
+            'mf script-pack run repo/generated-boundary check src/cli/index.ts',
+            'mf script-pack run repo/generated-boundary check dist/cli/index.js --json',
+            'mf script-pack run repo/generated-boundary check AGENTS.md .mustflow/config/manifest.lock.toml',
+        ],
+        exitCodes: [
+            { label: '0', description: t(lang, 'generatedBoundary.help.exit.ok') },
+            { label: '1', description: t(lang, 'generatedBoundary.help.exit.fail') },
+        ],
+    }, lang);
+}
+function parseGeneratedBoundaryOptions(args, lang) {
+    const [action, ...rest] = args;
+    const parsed = parseCliOptions(rest, GENERATED_BOUNDARY_OPTIONS, { allowPositionals: true });
+    const json = hasParsedCliOption(parsed, '--json');
+    if (action !== 'check') {
+        return {
+            action: 'check',
+            json,
+            paths: parsed.positionals,
+            error: action
+                ? t(lang, 'generatedBoundary.error.unknownAction', { action })
+                : t(lang, 'generatedBoundary.error.missingAction'),
+        };
+    }
+    if (parsed.error) {
+        return { action, json, paths: parsed.positionals, error: formatCliOptionParseError(parsed.error, lang) };
+    }
+    if (parsed.positionals.length === 0) {
+        return { action, json, paths: parsed.positionals, error: t(lang, 'generatedBoundary.error.missingPath') };
+    }
+    return { action, json, paths: parsed.positionals };
+}
+function renderGeneratedBoundarySummary(report, lang) {
+    const lines = [
+        t(lang, 'generatedBoundary.title'),
+        `${t(lang, 'scriptPack.label.script')}: ${GENERATED_BOUNDARY_SCRIPT_REF}`,
+        `${t(lang, 'label.status')}: ${report.status}`,
+        `${t(lang, 'generatedBoundary.label.checkedTargets')}: ${report.targets.length}`,
+        `${t(lang, 'generatedBoundary.label.findings')}: ${report.findings.length}`,
+    ];
+    if (report.targets.length > 0) {
+        lines.push(t(lang, 'generatedBoundary.label.targets'));
+        for (const target of report.targets) {
+            const boundaries = target.matched_boundaries.length === 0 ? t(lang, 'value.none') : target.matched_boundaries.join(', ');
+            lines.push(`- ${target.path}: ${target.kind}, ${t(lang, 'generatedBoundary.label.boundaries')}: ${boundaries}`);
+        }
+    }
+    if (report.findings.length > 0) {
+        lines.push(t(lang, 'generatedBoundary.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, 'generatedBoundary.label.issues'), ...report.issues.map((issue) => `- ${issue}`));
+    }
+    if (report.findings.length === 0 && report.issues.length === 0) {
+        lines.push(t(lang, 'generatedBoundary.clean'));
+    }
+    return lines.join('\n');
+}
+export function runRepoGeneratedBoundaryScript(args, reporter, lang = 'en') {
+    if (hasCliOptionToken(args, '--help', ['-h'])) {
+        reporter.stdout(getRepoGeneratedBoundaryHelp(lang));
+        return 0;
+    }
+    const options = parseGeneratedBoundaryOptions(args, lang);
+    if (options.error) {
+        printUsageError(reporter, options.error, 'mf script-pack run repo/generated-boundary --help', getRepoGeneratedBoundaryHelp(lang), lang);
+        return 1;
+    }
+    const report = inspectGeneratedBoundary(resolveMustflowRoot(), { paths: options.paths });
+    if (options.json) {
+        reporter.stdout(JSON.stringify(report, null, 2));
+        return report.ok ? 0 : 1;
+    }
+    reporter.stdout(renderGeneratedBoundarySummary(report, lang));
+    return report.ok ? 0 : 1;
+}

package/dist/core/generated-boundary.js

@@ -0,0 +1,231 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync } from 'node:fs';
+import path from 'node:path';
+import { isRecord, readMustflowConfigIfExists, readStringArray } from './config-loading.js';
+import { ensureInside } from './safe-filesystem.js';
+export const GENERATED_BOUNDARY_PACK_ID = 'repo';
+export const GENERATED_BOUNDARY_SCRIPT_ID = 'generated-boundary';
+export const GENERATED_BOUNDARY_SCRIPT_REF = `${GENERATED_BOUNDARY_PACK_ID}/${GENERATED_BOUNDARY_SCRIPT_ID}`;
+const BUILTIN_GENERATED_PATTERNS = [
+    'REPO_MAP.md',
+    '.mustflow/config/manifest.lock.toml',
+    '.mustflow/state/**',
+    '.mustflow/cache/**',
+    'dist/**',
+    'build/**',
+    'coverage/**',
+    '.next/**',
+    '.turbo/**',
+];
+const BUILTIN_VENDOR_PATTERNS = ['node_modules/**', 'vendor/**', 'third_party/**'];
+const BUILTIN_CACHE_PATTERNS = ['.cache/**', '.parcel-cache/**', '.pytest_cache/**'];
+const BUILTIN_PROTECTED_PATTERNS = ['.git/**', '**/*.pem', '**/*.key', '**/.env'];
+const CATEGORY_FINDING = {
+    generated: { code: 'generated_boundary_generated_path', severity: 'medium' },
+    ignored: { code: 'generated_boundary_ignored_path', severity: 'medium' },
+    protected: { code: 'generated_boundary_protected_path', severity: 'critical' },
+    vendor: { code: 'generated_boundary_vendor_path', severity: 'high' },
+    cache: { code: 'generated_boundary_cache_path', severity: 'medium' },
+    outside_root: { code: 'generated_boundary_path_outside_root', severity: 'high' },
+};
+function toPosixPath(value) {
+    return value.replace(/\\/gu, '/');
+}
+function normalizeRelativePath(value) {
+    return toPosixPath(value).replace(/^\.\/+/u, '').replace(/\/+$/u, '') || '.';
+}
+function uniqueSorted(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+function escapeRegExp(value) {
+    return value.replace(/[\\^$+?.()|[\]{}]/gu, '\\$&');
+}
+function globToRegExp(pattern) {
+    const normalized = normalizeRelativePath(pattern).replace(/^\/+/u, '');
+    let source = '^';
+    for (let index = 0; index < normalized.length;) {
+        if (normalized.startsWith('**', index)) {
+            source += '.*';
+            index += 2;
+            continue;
+        }
+        const character = normalized[index];
+        if (character === '*') {
+            source += '[^/]*';
+            index += 1;
+            continue;
+        }
+        if (character === '?') {
+            source += '[^/]';
+            index += 1;
+            continue;
+        }
+        source += escapeRegExp(character ?? '');
+        index += 1;
+    }
+    return new RegExp(`${source}$`, 'u');
+}
+function patternMatches(pattern, relativePath) {
+    const normalizedPattern = normalizeRelativePath(pattern);
+    const normalizedPath = normalizeRelativePath(relativePath);
+    if (normalizedPattern.endsWith('/**')) {
+        const base = normalizedPattern.slice(0, -3);
+        if (normalizedPath === base || normalizedPath.startsWith(`${base}/`)) {
+            return true;
+        }
+    }
+    if (globToRegExp(normalizedPattern).test(normalizedPath)) {
+        return true;
+    }
+    return normalizedPattern.startsWith('**/') && globToRegExp(normalizedPattern.slice(3)).test(normalizedPath);
+}
+function readPatternTable(config, tableName, key) {
+    const table = config?.[tableName];
+    return isRecord(table) ? (readStringArray(table, key) ?? []) : [];
+}
+function createPolicy(projectRoot, issues) {
+    let config;
+    try {
+        config = readMustflowConfigIfExists(projectRoot);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        issues.push(`Could not read .mustflow/config/mustflow.toml: ${message}`);
+    }
+    return {
+        config_path: '.mustflow/config/mustflow.toml',
+        config_loaded: config !== undefined,
+        generated_patterns: readPatternTable(config, 'document_roots', 'generated'),
+        ignored_patterns: readPatternTable(config, 'document_roots', 'ignored'),
+        protected_patterns: readPatternTable(config, 'edit_policy', 'protected'),
+        builtin_generated_patterns: [...BUILTIN_GENERATED_PATTERNS],
+        builtin_vendor_patterns: [...BUILTIN_VENDOR_PATTERNS],
+        builtin_cache_patterns: [...BUILTIN_CACHE_PATTERNS],
+        builtin_protected_patterns: [...BUILTIN_PROTECTED_PATTERNS],
+    };
+}
+function createBoundaryPatterns(policy) {
+    return [
+        ...policy.generated_patterns.map((pattern) => ({ category: 'generated', pattern, source: 'mustflow_config' })),
+        ...policy.ignored_patterns.map((pattern) => ({ category: 'ignored', pattern, source: 'mustflow_config' })),
+        ...policy.protected_patterns.map((pattern) => ({ category: 'protected', pattern, source: 'mustflow_config' })),
+        ...policy.builtin_generated_patterns.map((pattern) => ({ category: 'generated', pattern, source: 'builtin' })),
+        ...policy.builtin_vendor_patterns.map((pattern) => ({ category: 'vendor', pattern, source: 'builtin' })),
+        ...policy.builtin_cache_patterns.map((pattern) => ({ category: 'cache', pattern, source: 'builtin' })),
+        ...policy.builtin_protected_patterns.map((pattern) => ({ category: 'protected', pattern, source: 'builtin' })),
+    ];
+}
+function targetKind(absolutePath) {
+    if (!existsSync(absolutePath)) {
+        return { exists: false, kind: 'missing' };
+    }
+    const stats = lstatSync(absolutePath);
+    if (stats.isFile()) {
+        return { exists: true, kind: 'file' };
+    }
+    if (stats.isDirectory()) {
+        return { exists: true, kind: 'directory' };
+    }
+    return { exists: true, kind: 'other' };
+}
+function makeFinding(code, severity, targetPath, boundary, message, pattern, source) {
+    return { code, severity, message, path: targetPath, boundary, pattern, source };
+}
+function createInputHash(policy, targets, issues) {
+    const inputState = {
+        policy,
+        targets: targets.map((target) => ({
+            input: target.input,
+            path: target.path,
+            exists: target.exists,
+            kind: target.kind,
+            matched_patterns: target.matched_patterns,
+        })),
+        issues,
+    };
+    return `sha256:${createHash('sha256').update(JSON.stringify(inputState)).digest('hex')}`;
+}
+export function inspectGeneratedBoundary(projectRoot, options) {
+    const root = path.resolve(projectRoot);
+    const issues = [];
+    const policy = createPolicy(root, issues);
+    const patterns = createBoundaryPatterns(policy);
+    const targets = [];
+    const findings = [];
+    for (const targetPath of options.paths) {
+        let relativePath = targetPath;
+        let absolutePath;
+        try {
+            absolutePath = path.resolve(process.cwd(), targetPath);
+            ensureInside(root, absolutePath);
+            relativePath = normalizeRelativePath(path.relative(root, absolutePath));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            issues.push(message);
+            targets.push({
+                input: targetPath,
+                path: targetPath,
+                exists: null,
+                kind: 'unknown',
+                matched_boundaries: ['outside_root'],
+                matched_patterns: [],
+            });
+            findings.push(makeFinding('generated_boundary_path_outside_root', 'high', targetPath, 'outside_root', message, null, null));
+            continue;
+        }
+        let existence;
+        try {
+            existence = targetKind(absolutePath);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            issues.push(`${relativePath}: ${message}`);
+            targets.push({
+                input: targetPath,
+                path: relativePath,
+                exists: null,
+                kind: 'unknown',
+                matched_boundaries: [],
+                matched_patterns: [],
+            });
+            findings.push(makeFinding('generated_boundary_unreadable_path', 'high', relativePath, 'protected', message, null, null));
+            continue;
+        }
+        const matchedPatterns = patterns.filter((candidate) => patternMatches(candidate.pattern, relativePath));
+        const matchedBoundaries = uniqueSorted(matchedPatterns.map((candidate) => candidate.category));
+        targets.push({
+            input: targetPath,
+            path: relativePath,
+            exists: existence.exists,
+            kind: existence.kind,
+            matched_boundaries: matchedBoundaries,
+            matched_patterns: matchedPatterns,
+        });
+        for (const match of matchedPatterns) {
+            const finding = CATEGORY_FINDING[match.category];
+            findings.push(makeFinding(finding.code, finding.severity, relativePath, match.category, `${relativePath} matches ${match.category} boundary pattern ${match.pattern}.`, match.pattern, match.source));
+        }
+    }
+    const status = findings.some((finding) => ['generated_boundary_path_outside_root', 'generated_boundary_unreadable_path'].includes(finding.code))
+        ? 'error'
+        : findings.length > 0 || issues.length > 0
+            ? 'failed'
+            : 'passed';
+    return {
+        schema_version: '1',
+        command: 'script-pack',
+        pack_id: GENERATED_BOUNDARY_PACK_ID,
+        script_id: GENERATED_BOUNDARY_SCRIPT_ID,
+        script_ref: GENERATED_BOUNDARY_SCRIPT_REF,
+        action: 'check',
+        status,
+        ok: status === 'passed',
+        mustflow_root: root,
+        policy,
+        input_hash: createInputHash(policy, targets, issues),
+        targets,
+        findings,
+        issues,
+    };
+}

package/dist/core/public-json-contracts.js

@@ -215,6 +215,23 @@ const PUBLIC_JSON_SCHEMA_CONTRACTS = [
         documented: true,
         installedCommand: ['mf', 'script-pack', 'list', '--json'],
     },
+    {
+        id: 'script-pack-suggestion-report',
+        schemaFile: 'script-pack-suggestion-report.schema.json',
+        producer: 'mf script-pack suggest --json',
+        packaged: true,
+        documented: true,
+        installedCommand: [
+            'mf',
+            'script-pack',
+            'suggest',
+            '--path',
+            'AGENTS.md',
+            '--phase',
+            'before_change',
+            '--json',
+        ],
+    },
     {
         id: 'text-budget-report',
         schemaFile: 'text-budget-report.schema.json',
@@ -234,6 +251,24 @@ const PUBLIC_JSON_SCHEMA_CONTRACTS = [
         ],
         expectedExitCodes: [0, 1],
     },
+    {
+        id: 'generated-boundary-report',
+        schemaFile: 'generated-boundary-report.schema.json',
+        producer: 'mf script-pack run repo/generated-boundary check <path...> --json',
+        packaged: true,
+        documented: true,
+        installedCommand: [
+            'mf',
+            'script-pack',
+            'run',
+            'repo/generated-boundary',
+            'check',
+            'AGENTS.md',
+            '.mustflow/config/manifest.lock.toml',
+            '--json',
+        ],
+        expectedExitCodes: [0, 1],
+    },
     {
         id: 'skill-route-report',
         schemaFile: 'skill-route-report.schema.json',