mustflow 2.22.5 → 2.22.9

package/README.md

@@ -367,6 +367,12 @@ bun run docs:check
 bun run check:install
 ```
 
+When Bun is not available, maintainers can still run the core CLI and package metadata checks with Node/npm:
+
+```sh
+npm run check:core:node
+```
+
 Agents working in this repository should prefer the configured mustflow intents for routine verification.
 
 ```sh
@@ -376,6 +382,7 @@ mf run test_related
 mf run test
 mf run test_coverage
 mf run test_release
+mf run maintainer_check_node
 mf run docs_validate_fast
 mf run docs_validate
 mf run mustflow_check
@@ -413,6 +420,7 @@ The npm package includes only:
 dist/
 templates/
 schemas/
+examples/
 README.md
 LICENSE
 ```

package/dist/cli/commands/classify.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { createChangeClassificationReport, } from '../../core/change-classification.js';
+import { createCorrelationId } from '../../core/correlation-id.js';
 import { writeJsonFileInsideWithoutSymlinks } from '../../core/safe-filesystem.js';
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
 import { requireGitChangedFiles } from '../lib/git-changes.js';
@@ -71,6 +72,7 @@ export function createClassifyOutput(projectRoot, source, paths) {
     return {
         schema_version: CLASSIFY_SCHEMA_VERSION,
         command: 'classify',
+        correlation_id: createCorrelationId('classify'),
         mustflow_root: projectRoot,
         ...createChangeClassificationReport(source, files),
     };

package/dist/cli/commands/dashboard.js

@@ -2,7 +2,7 @@ import { createHash, randomBytes } from 'node:crypto';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import http from 'node:http';
 import path from 'node:path';
-import { openPathInFileManager, openUrlInBrowser } from '../lib/browser-open.js';
+import { openUrlInBrowser } from '../lib/browser-open.js';
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
 import { renderDashboardHtml, } from '../lib/dashboard-html.js';
 import { DashboardExportPathError, writeDashboardExport, } from '../lib/dashboard-export.js';
@@ -12,8 +12,9 @@ import { parseSkillIndexRoutes } from '../../core/skill-route-alignment.js';
 import { getAgentContext } from '../lib/agent-context.js';
 import { readGitChangedFiles } from '../lib/git-changes.js';
 import { isRecord, readCommandContract, readPositiveInteger, readString, readStringArray, } from '../lib/command-contract.js';
-import { readDashboardPreferences, updateDashboardPreferences, } from '../lib/dashboard-preferences.js';
-import { DOC_REVIEW_LEDGER_RELATIVE_PATH, isDocReviewStatus, isReviewerKind, listDocReviewEntries, markDocReviewEntry, } from '../lib/doc-review-ledger.js';
+import { readDashboardPreferences, } from '../lib/dashboard-preferences.js';
+import { DOC_REVIEW_LEDGER_RELATIVE_PATH, isDocReviewStatus, listDocReviewEntries, } from '../lib/doc-review-ledger.js';
+import { markDashboardDocReviewFromPayload, openDashboardMustflowFolder, updateDashboardPreferencesFromPayload, } from '../lib/dashboard-mutations.js';
 import { MANIFEST_LOCK_RELATIVE_PATH, inspectManifestLock } from '../lib/manifest-lock.js';
 import { getLocalIndexDatabasePath, readLatestLocalVerificationReadModelQueries, readLocalCommandEffectGraphs, } from '../lib/local-index.js';
 import { readPackageMetadata } from '../lib/package-info.js';
@@ -26,7 +27,6 @@ const DEFAULT_DASHBOARD_HOST = '127.0.0.1';
 const DEFAULT_DASHBOARD_PORT = 0;
 const MAX_REQUEST_BYTES = 64 * 1024;
 const LOCAL_DASHBOARD_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']);
-const DOC_REVIEW_BULK_PAYLOAD_FIELDS = ['paths', 'documents', 'entries'];
 const RELEASE_FILE_PATTERNS = [
     /^package\.json$/u,
     /^bun\.lockb?$/u,
@@ -323,66 +323,6 @@ async function readRequestJson(request) {
     const rawBody = Buffer.concat(chunks).toString('utf8');
     return rawBody.trim().length === 0 ? {} : JSON.parse(rawBody);
 }
-function readUpdatePayload(value) {
-    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-        throw new Error('Request body must be a JSON object.');
-    }
-    const updates = value.updates;
-    if (!Array.isArray(updates)) {
-        throw new Error('Request body must include an updates array.');
-    }
-    return updates.map((entry) => {
-        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
-            throw new Error('Each update must be a JSON object.');
-        }
-        const update = entry;
-        if (typeof update.id !== 'string' || update.id.trim().length === 0) {
-            throw new Error('Each update must include an id.');
-        }
-        return { id: update.id, value: update.value };
-    });
-}
-function readOptionalStringField(value, key) {
-    const field = value[key];
-    return typeof field === 'string' && field.trim().length > 0 ? field.trim() : undefined;
-}
-function readRequiredStringField(value, key) {
-    const field = readOptionalStringField(value, key);
-    if (!field) {
-        throw new Error(`${key} is required.`);
-    }
-    return field;
-}
-function readDocReviewPayload(value) {
-    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-        throw new Error('Request body must be a JSON object.');
-    }
-    const payload = value;
-    for (const field of DOC_REVIEW_BULK_PAYLOAD_FIELDS) {
-        if (field in payload) {
-            throw new Error('Bulk documentation review updates require a separate confirmed flow.');
-        }
-    }
-    const status = readRequiredStringField(payload, 'status');
-    if (status !== 'approved' && status !== 'needs_human' && status !== 'ignored') {
-        throw new Error('status must be approved, needs_human, or ignored.');
-    }
-    const reviewerKind = readRequiredStringField(payload, 'reviewerKind');
-    if (!isReviewerKind(reviewerKind)) {
-        throw new Error('reviewerKind must be human, llm, tool, or external.');
-    }
-    return {
-        path: readRequiredStringField(payload, 'path'),
-        status,
-        reviewerKind,
-        reviewerId: readRequiredStringField(payload, 'reviewerId'),
-        reviewerLabel: readOptionalStringField(payload, 'reviewerLabel'),
-        reviewerProvider: readOptionalStringField(payload, 'reviewerProvider'),
-        reviewerModel: readOptionalStringField(payload, 'reviewerModel'),
-        reviewerCommandIntent: readOptionalStringField(payload, 'reviewerCommandIntent'),
-        summary: readOptionalStringField(payload, 'summary'),
-    };
-}
 function renderDocReviewResponse(projectRoot, requestUrl) {
     const status = requestUrl.searchParams.get('status');
     if (status && !isDocReviewStatus(status)) {
@@ -858,7 +798,7 @@ export async function runDashboard(args, reporter, lang = 'en') {
                 }
                 if (request.method === 'POST') {
                     const body = await readRequestJson(request);
-                    sendJson(response, 200, updateDashboardPreferences(projectRoot, readUpdatePayload(body)));
+                    sendJson(response, 200, updateDashboardPreferencesFromPayload(projectRoot, body));
                     return;
                 }
             }
@@ -871,12 +811,12 @@ export async function runDashboard(args, reporter, lang = 'en') {
                     sendText(response, 405, 'Method not allowed');
                     return;
                 }
-                const mustflowPath = path.join(projectRoot, '.mustflow');
-                if (!existsSync(mustflowPath)) {
+                const openResult = openDashboardMustflowFolder(projectRoot);
+                if (openResult === 'missing') {
                     sendText(response, 404, '.mustflow folder not found');
                     return;
                 }
-                if (!openPathInFileManager(mustflowPath)) {
+                if (openResult === 'unavailable') {
                     sendText(response, 500, 'No file manager opener is available for this platform');
                     return;
                 }
@@ -894,7 +834,7 @@ export async function runDashboard(args, reporter, lang = 'en') {
                 }
                 if (request.method === 'POST') {
                     const body = await readRequestJson(request);
-                    markDocReviewEntry(projectRoot, readDocReviewPayload(body));
+                    markDashboardDocReviewFromPayload(projectRoot, body);
                     sendJson(response, 200, renderDocReviewResponse(projectRoot, requestUrl));
                     return;
                 }

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

@@ -1,6 +1,7 @@
 import { createRunReceipt, createRunReceiptRelativePath, } from '../../../core/run-receipt.js';
 export function assembleRunReceipt(input) {
     return createRunReceipt({
+        correlationId: input.correlationId,
         intent: input.intentName,
         status: input.runStatus,
         timedOut: input.runStatus === 'timed_out',

package/dist/cli/commands/run.js

@@ -1,10 +1,12 @@
 import { performance } from 'node:perf_hooks';
 import { createCommandEnv } from '../../core/command-env.js';
+import { createCorrelationId } from '../../core/correlation-id.js';
 import { printUsageError, renderCliError, renderHelp } from '../lib/cli-output.js';
 import { readCommandContract, readMustflowConfigIfExists } from '../../core/config-loading.js';
 import { resolveRunReceiptRetentionPolicy } from '../../core/retention-policy.js';
 import { t } from '../lib/i18n.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
+import { ALLOW_UNTRUSTED_ROOT_OPTION, assessRunRootTrust } from '../lib/run-root-trust.js';
 import { createRunPlan, createRunPreview, renderRunPreviewText, } from '../lib/run-plan.js';
 import { writeRunReceipt, } from '../../core/run-receipt.js';
 import { recordRunPerformanceHistory } from '../../core/run-performance-history.js';
@@ -92,6 +94,7 @@ export function getRunHelp(lang = 'en') {
             { 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: 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'],
@@ -121,7 +124,7 @@ export async function runRun(args, reporter, lang = 'en', options = {}) {
         reporter.stdout(getRunHelp(lang));
         return 0;
     }
-    const supportedOptions = new Set(['--json', '--dry-run', '--plan-only']);
+    const supportedOptions = new Set(['--json', '--dry-run', '--plan-only', ALLOW_UNTRUSTED_ROOT_OPTION]);
     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);
@@ -130,6 +133,7 @@ export async function runRun(args, reporter, lang = 'en', options = {}) {
     const json = args.includes('--json');
     const dryRun = args.includes('--dry-run');
     const planOnly = args.includes('--plan-only');
+    const allowUntrustedRoot = args.includes(ALLOW_UNTRUSTED_ROOT_OPTION);
     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);
@@ -146,6 +150,14 @@ export async function runRun(args, reporter, lang = 'en', options = {}) {
         return 1;
     }
     const projectRoot = profiler.measure('root_detection', () => resolveMustflowRoot());
+    const rootTrust = profiler.measure('root_trust', () => assessRunRootTrust(projectRoot));
+    if (!previewMode && !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 1;
+    }
     const contract = profiler.measure('command_contract', () => readCommandContract(projectRoot));
     const plan = profiler.measure('plan_creation', () => createRunPlan(projectRoot, contract, intentName, { testTargets: options.testTargets }));
     if (previewMode) {
@@ -208,6 +220,7 @@ export async function runRun(args, reporter, lang = 'en', options = {}) {
         }
     }
     const receipt = profiler.measure('receipt_create', () => assembleRunReceipt({
+        correlationId: options.correlationId ?? createCorrelationId('run'),
         intentName,
         runStatus,
         startedAt,

package/dist/cli/commands/verify/evidence-input.js

@@ -0,0 +1,269 @@
+import { readVerifyJsonInputFile } from './input.js';
+function isPlainRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function isExternalEvidenceStatus(value) {
+    return value === 'passed' || value === 'failed' || value === 'cancelled' || value === 'unknown';
+}
+function isLegacyReproEvidenceStatus(value) {
+    return value === 'present' || value === 'unavailable' || value === 'missing';
+}
+function isReproBeforeFixStatus(value) {
+    return value === 'reproduced' || value === 'unavailable' || value === 'missing';
+}
+function isReproBeforeFixOutcome(value) {
+    return value === 'failed_as_expected' || value === 'failed_differently' || value === 'passed_unexpectedly' || value === null;
+}
+function isReproAfterFixStatus(value) {
+    return value === 'passed' || value === 'failed' || value === 'unavailable' || value === 'missing';
+}
+function isReproAfterFixOutcome(value) {
+    return value === 'passed_expected_behavior' || value === 'failed_same_route' || value === 'failed_differently' || value === null;
+}
+function isReproRegressionGuardStatus(value) {
+    return value === 'passed' || value === 'failed' || value === 'unavailable' || value === 'missing';
+}
+function isReproRouteKind(value) {
+    return (value === 'test' ||
+        value === 'cli' ||
+        value === 'browser' ||
+        value === 'api' ||
+        value === 'manual' ||
+        value === 'unknown' ||
+        value === null);
+}
+function readOptionalString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function readRouteStep(value, index) {
+    if (!isPlainRecord(value)) {
+        return {
+            ordinal: index + 1,
+            action: null,
+            target: null,
+            input_digest: null,
+            observation_digest: null,
+            summary: null,
+        };
+    }
+    const ordinal = typeof value.ordinal === 'number' && Number.isInteger(value.ordinal) && value.ordinal > 0 ? value.ordinal : index + 1;
+    return {
+        ordinal,
+        action: readOptionalString(value.action),
+        target: readOptionalString(value.target),
+        input_digest: readOptionalString(value.input_digest),
+        observation_digest: readOptionalString(value.observation_digest),
+        summary: readOptionalString(value.summary),
+    };
+}
+function readReproductionRoute(value) {
+    if (!isPlainRecord(value)) {
+        return {
+            route_id: null,
+            route_kind: null,
+            route_digest: null,
+            failure_oracle_hash: null,
+            steps: [],
+        };
+    }
+    const routeKind = value.route_kind ?? null;
+    if (!isReproRouteKind(routeKind)) {
+        throw new Error('invalid_repro_evidence_file');
+    }
+    const rawSteps = Array.isArray(value.steps) ? value.steps : [];
+    return {
+        route_id: readOptionalString(value.route_id),
+        route_kind: routeKind,
+        route_digest: readOptionalString(value.route_digest),
+        failure_oracle_hash: readOptionalString(value.failure_oracle_hash),
+        steps: rawSteps.map((step, index) => readRouteStep(step, index)),
+    };
+}
+function readLegacyReproEvidenceItem(value) {
+    if (!isPlainRecord(value)) {
+        return {
+            status: 'missing',
+            summary: null,
+            reason: null,
+        };
+    }
+    if (!isLegacyReproEvidenceStatus(value.status)) {
+        throw new Error('invalid_repro_evidence_file');
+    }
+    return {
+        status: value.status,
+        summary: readOptionalString(value.summary),
+        reason: readOptionalString(value.reason),
+    };
+}
+function legacyBeforeFixEvidence(value) {
+    const item = readLegacyReproEvidenceItem(value);
+    return {
+        status: item.status === 'present' ? 'reproduced' : item.status,
+        outcome: item.status === 'present' ? 'failed_as_expected' : null,
+        receipt_path: null,
+        receipt_sha256: null,
+        verification_plan_id: null,
+        summary: item.summary,
+        reason: item.reason,
+    };
+}
+function legacyAfterFixEvidence(value) {
+    const item = readLegacyReproEvidenceItem(value);
+    return {
+        status: item.status === 'present' ? 'passed' : item.status,
+        outcome: item.status === 'present' ? 'passed_expected_behavior' : null,
+        same_route_as: null,
+        receipt_path: null,
+        receipt_sha256: null,
+        verification_plan_id: null,
+        summary: item.summary,
+        reason: item.reason,
+    };
+}
+function legacyRegressionGuardEvidence(value) {
+    const item = readLegacyReproEvidenceItem(value);
+    return {
+        status: item.status === 'present' ? 'passed' : item.status,
+        intent: null,
+        test_path: null,
+        receipt_path: null,
+        receipt_sha256: null,
+        verification_plan_id: null,
+        summary: item.summary,
+        reason: item.reason,
+    };
+}
+function readBeforeFixEvidence(value) {
+    if (!isPlainRecord(value)) {
+        return {
+            status: 'missing',
+            outcome: null,
+            receipt_path: null,
+            receipt_sha256: null,
+            verification_plan_id: null,
+            summary: null,
+            reason: null,
+        };
+    }
+    const outcome = value.outcome ?? null;
+    if (!isReproBeforeFixStatus(value.status) || !isReproBeforeFixOutcome(outcome)) {
+        throw new Error('invalid_repro_evidence_file');
+    }
+    return {
+        status: value.status,
+        outcome,
+        receipt_path: readOptionalString(value.receipt_path),
+        receipt_sha256: readOptionalString(value.receipt_sha256),
+        verification_plan_id: readOptionalString(value.verification_plan_id),
+        summary: readOptionalString(value.summary),
+        reason: readOptionalString(value.reason),
+    };
+}
+function readAfterFixEvidence(value) {
+    if (!isPlainRecord(value)) {
+        return {
+            status: 'missing',
+            outcome: null,
+            same_route_as: null,
+            receipt_path: null,
+            receipt_sha256: null,
+            verification_plan_id: null,
+            summary: null,
+            reason: null,
+        };
+    }
+    const outcome = value.outcome ?? null;
+    if (!isReproAfterFixStatus(value.status) || !isReproAfterFixOutcome(outcome)) {
+        throw new Error('invalid_repro_evidence_file');
+    }
+    return {
+        status: value.status,
+        outcome,
+        same_route_as: readOptionalString(value.same_route_as),
+        receipt_path: readOptionalString(value.receipt_path),
+        receipt_sha256: readOptionalString(value.receipt_sha256),
+        verification_plan_id: readOptionalString(value.verification_plan_id),
+        summary: readOptionalString(value.summary),
+        reason: readOptionalString(value.reason),
+    };
+}
+function readRegressionGuardEvidence(value) {
+    if (!isPlainRecord(value)) {
+        return {
+            status: 'missing',
+            intent: null,
+            test_path: null,
+            receipt_path: null,
+            receipt_sha256: null,
+            verification_plan_id: null,
+            summary: null,
+            reason: null,
+        };
+    }
+    if (!isReproRegressionGuardStatus(value.status)) {
+        throw new Error('invalid_repro_evidence_file');
+    }
+    return {
+        status: value.status,
+        intent: readOptionalString(value.intent),
+        test_path: readOptionalString(value.test_path),
+        receipt_path: readOptionalString(value.receipt_path),
+        receipt_sha256: readOptionalString(value.receipt_sha256),
+        verification_plan_id: readOptionalString(value.verification_plan_id),
+        summary: readOptionalString(value.summary),
+        reason: readOptionalString(value.reason),
+    };
+}
+export function readReproEvidenceFile(projectRoot, inputPath) {
+    const parsed = readVerifyJsonInputFile(projectRoot, inputPath, 'invalid_repro_evidence_file');
+    if (!isPlainRecord(parsed) || parsed.schema_version !== '1' || parsed.command !== 'repro-evidence') {
+        throw new Error('unsupported_repro_evidence_source');
+    }
+    const regressionGuard = isPlainRecord(parsed.regression_guard) && isReproRegressionGuardStatus(parsed.regression_guard.status)
+        ? readRegressionGuardEvidence(parsed.regression_guard)
+        : legacyRegressionGuardEvidence(parsed.regression_guard);
+    return {
+        source: 'repro_first_debug',
+        authority: 'claim_evidence',
+        reported_symptom: readOptionalString(parsed.reported_symptom),
+        expected_behavior: readOptionalString(parsed.expected_behavior),
+        observed_behavior: readOptionalString(parsed.observed_behavior),
+        reproduction_route: readReproductionRoute(parsed.reproduction_route),
+        before_fix: isPlainRecord(parsed.before_fix)
+            ? readBeforeFixEvidence(parsed.before_fix)
+            : legacyBeforeFixEvidence(parsed.evidence_before_fix),
+        after_fix: isPlainRecord(parsed.after_fix)
+            ? readAfterFixEvidence(parsed.after_fix)
+            : legacyAfterFixEvidence(parsed.evidence_after_fix),
+        regression_guard: regressionGuard,
+    };
+}
+export function readExternalEvidenceFile(projectRoot, inputPath) {
+    const parsed = readVerifyJsonInputFile(projectRoot, inputPath, 'invalid_external_evidence_file');
+    if (!isPlainRecord(parsed) || parsed.schema_version !== '1' || parsed.command !== 'external-evidence') {
+        throw new Error('unsupported_external_evidence_source');
+    }
+    if (!Array.isArray(parsed.checks)) {
+        throw new Error('invalid_external_evidence_file');
+    }
+    return parsed.checks.map((check) => {
+        if (!isPlainRecord(check) ||
+            typeof check.provider !== 'string' ||
+            check.provider.length === 0 ||
+            typeof check.name !== 'string' ||
+            check.name.length === 0 ||
+            !isExternalEvidenceStatus(check.status)) {
+            throw new Error('invalid_external_evidence_file');
+        }
+        return {
+            source: 'external_ci',
+            authority: 'supporting_only',
+            provider: check.provider,
+            name: check.name,
+            status: check.status,
+            url: readOptionalString(check.url),
+            summary: readOptionalString(check.summary),
+        };
+    });
+}