mustflow 2.22.17 → 2.22.47

package/dist/cli/commands/api.js

@@ -0,0 +1,874 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { createClassifyOutput } from './classify.js';
+import { createChangeVerificationReport, } from '../../core/change-verification.js';
+import { readUtf8FileInsideWithoutSymlinks } from '../../core/safe-filesystem.js';
+import { createVerificationPlanId } from '../../core/verification-plan-id.js';
+import { printUsageError, renderHelp } from '../lib/cli-output.js';
+import { getAgentContext } from '../lib/agent-context.js';
+import { isRecord, readCommandContract, readPositiveInteger, readString, readStringArray, } from '../lib/command-contract.js';
+import { readGitChangedFiles } from '../lib/git-changes.js';
+import { t } from '../lib/i18n.js';
+import { resolveMustflowRoot } from '../lib/project-root.js';
+import { createRunPlan } from '../lib/run-plan.js';
+import { checkMustflowProjectReport } from '../lib/validation.js';
+const API_WORKSPACE_SUMMARY_SCHEMA_VERSION = '1';
+const API_COMMAND_CATALOG_SCHEMA_VERSION = '1';
+const API_VERIFICATION_PLAN_SCHEMA_VERSION = '1';
+const API_LATEST_EVIDENCE_SCHEMA_VERSION = '1';
+const API_DIFF_RISK_SCHEMA_VERSION = '1';
+const API_HEALTH_SCHEMA_VERSION = '1';
+const COMMANDS_RELATIVE_PATH = '.mustflow/config/commands.toml';
+const LATEST_RUN_RELATIVE_PATH = '.mustflow/state/runs/latest.json';
+const MUSTFLOW_JSON_MAX_BYTES = 1024 * 1024;
+export function getApiHelp(lang = 'en') {
+    return renderHelp({
+        usage: 'mf api <action> [options]',
+        summary: t(lang, 'api.help.summary'),
+        commands: [
+            {
+                label: 'workspace-summary',
+                description: t(lang, 'api.help.action.workspaceSummary'),
+            },
+            {
+                label: 'command-catalog',
+                description: t(lang, 'api.help.action.commandCatalog'),
+            },
+            {
+                label: 'verification-plan',
+                description: t(lang, 'api.help.action.verificationPlan'),
+            },
+            {
+                label: 'latest-evidence',
+                description: t(lang, 'api.help.action.latestEvidence'),
+            },
+            {
+                label: 'diff-risk',
+                description: t(lang, 'api.help.action.diffRisk'),
+            },
+            {
+                label: 'health',
+                description: t(lang, 'api.help.action.health'),
+            },
+        ],
+        options: [
+            { label: '--changed', description: t(lang, 'classify.help.option.changed') },
+            { label: '--json', description: t(lang, 'cli.option.json') },
+            { label: '-h, --help', description: t(lang, 'cli.option.help') },
+        ],
+        examples: [
+            'mf api workspace-summary --json',
+            'mf api command-catalog --json',
+            'mf api verification-plan --changed --json',
+            'mf api latest-evidence --json',
+            'mf api diff-risk --changed --json',
+            'mf api health --json',
+        ],
+        exitCodes: [
+            { label: '0', description: t(lang, 'api.help.exit.ok') },
+            { label: '1', description: t(lang, 'cli.common.invalidInput') },
+        ],
+    }, lang);
+}
+function summarizeCheck(projectRoot) {
+    const report = checkMustflowProjectReport(projectRoot, { strict: false });
+    return {
+        ok: report.issues.length === 0,
+        issue_count: report.issues.length,
+        warning_count: report.warnings.length,
+        issues: report.issues,
+        warnings: report.warnings,
+    };
+}
+function summarizeReadOrder(context) {
+    return {
+        required: context.read_order.map((entry) => entry.path),
+        optional: context.optional_read_order.map((entry) => entry.path),
+        missing_required: context.read_order.filter((entry) => !entry.exists).map((entry) => entry.path),
+        missing_optional: context.optional_read_order.filter((entry) => !entry.exists).map((entry) => entry.path),
+    };
+}
+function summarizeCommandSurface(projectRoot, context) {
+    const catalog = createCommandCatalogOutputForRoot(projectRoot);
+    const totalIntents = catalog.command_contract.parse_error === null ? catalog.command_contract.total_intents : context.command_contract.intents.length;
+    const runnableIntents = catalog.command_contract.parse_error === null
+        ? catalog.intents.filter((intent) => intent.runnable).map((intent) => intent.name)
+        : context.command_contract.runnable_intents;
+    const runnableCount = runnableIntents.length;
+    return {
+        path: context.command_contract.path,
+        exists: context.command_contract.exists,
+        total_intents: totalIntents,
+        runnable_intents: runnableIntents,
+        runnable_count: runnableCount,
+        non_runnable_count: Math.max(0, totalIntents - runnableCount),
+    };
+}
+function pathExists(projectRoot, relativePath) {
+    const resolved = path.resolve(projectRoot, ...relativePath.split('/'));
+    const root = path.resolve(projectRoot);
+    const relative = path.relative(root, resolved);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        return false;
+    }
+    return existsSync(resolved);
+}
+function summarizeSkillSurface(projectRoot) {
+    return {
+        index_path: '.mustflow/skills/INDEX.md',
+        index_exists: pathExists(projectRoot, '.mustflow/skills/INDEX.md'),
+        routes_path: '.mustflow/skills/routes.toml',
+        routes_exists: pathExists(projectRoot, '.mustflow/skills/routes.toml'),
+    };
+}
+function summarizeGitState(projectRoot) {
+    const result = readGitChangedFiles(projectRoot);
+    if (!result.ok) {
+        return {
+            status: 'unavailable',
+            changed_file_count: null,
+            changed_files: [],
+            error: result.message,
+        };
+    }
+    return {
+        status: 'available',
+        changed_file_count: result.files.length,
+        changed_files: result.files,
+        error: null,
+    };
+}
+function createRecommendedReadSurfaces(context) {
+    const surfaces = [
+        ...context.read_order.filter((entry) => entry.exists).map((entry) => entry.path),
+        ...context.optional_read_order.filter((entry) => entry.exists).map((entry) => entry.path),
+    ];
+    return [...new Set(surfaces)];
+}
+function createRecommendedNextCommands(output) {
+    if (!output.installed) {
+        return ['mf init --dry-run', 'mf init --yes'];
+    }
+    if (!output.check.ok) {
+        return ['mf check', 'mf status --json', 'mf update --dry-run'];
+    }
+    const commands = ['mf context --json', 'mf doctor --json', 'mf check --strict'];
+    if (output.git_state.status === 'available' && output.git_state.changed_file_count !== null && output.git_state.changed_file_count > 0) {
+        commands.push('mf classify --changed --json', 'mf verify --changed --plan-only --json');
+    }
+    return commands;
+}
+function isSafeIntentName(value) {
+    return /^[A-Za-z0-9_-]+$/u.test(value);
+}
+function commandForIntent(kind, intentName) {
+    if (!isSafeIntentName(intentName)) {
+        return null;
+    }
+    return kind === 'run' ? `mf run ${intentName}` : `mf run ${intentName} --dry-run --json`;
+}
+function acceptsTestTargets(intent) {
+    return isRecord(intent) && isRecord(intent.selection) && intent.selection.accepts_test_targets === true;
+}
+function readIntentStrings(intent, key) {
+    return intent ? (readStringArray(intent, key) ?? []) : [];
+}
+function toNullableBoolean(value) {
+    return typeof value === 'boolean' ? value : null;
+}
+function readIntentBoolean(intent, key) {
+    const value = intent?.[key];
+    return typeof value === 'boolean' ? value : null;
+}
+function getIntentMode(intent) {
+    if (!intent) {
+        return null;
+    }
+    if (readStringArray(intent, 'argv')) {
+        return 'argv';
+    }
+    return intent.mode === 'shell' && readString(intent, 'cmd') ? 'shell' : null;
+}
+function createCommandCatalogIntentFromError(contract, name, error) {
+    const rawIntent = isRecord(contract.intents[name]) ? contract.intents[name] : undefined;
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        name,
+        description: rawIntent ? readString(rawIntent, 'description') ?? null : null,
+        kind: rawIntent ? readString(rawIntent, 'kind') ?? null : null,
+        status: rawIntent ? readString(rawIntent, 'status') ?? null : null,
+        lifecycle: rawIntent ? readString(rawIntent, 'lifecycle') ?? null : null,
+        run_policy: rawIntent ? readString(rawIntent, 'run_policy') ?? null : null,
+        runnable: false,
+        reason_code: 'catalog_error',
+        detail: message,
+        run_command: null,
+        preview_command: commandForIntent('preview', name),
+        mode: getIntentMode(rawIntent),
+        cwd: null,
+        timeout_seconds: rawIntent ? readPositiveInteger(rawIntent, 'timeout_seconds') ?? null : null,
+        kill_after_seconds: null,
+        max_output_bytes: null,
+        success_exit_codes: null,
+        required_after: readIntentStrings(rawIntent, 'required_after'),
+        writes: readIntentStrings(rawIntent, 'writes'),
+        effect_count: Array.isArray(rawIntent?.effects) ? rawIntent.effects.length : 0,
+        network: readIntentBoolean(rawIntent, 'network'),
+        destructive: readIntentBoolean(rawIntent, 'destructive'),
+        accepts_test_targets: acceptsTestTargets(rawIntent),
+        env_policy: rawIntent ? readString(rawIntent, 'env_policy') ?? null : null,
+        env_allowlist: readIntentStrings(rawIntent, 'env_allowlist'),
+        precondition_count: 0,
+        active_lock_conflict_count: 0,
+        stale_active_lock_count: 0,
+        agent_action: rawIntent ? readString(rawIntent, 'agent_action') ?? null : null,
+        manual_start_hint: rawIntent ? readString(rawIntent, 'manual_start_hint') ?? null : null,
+        health_check_url: rawIntent ? readString(rawIntent, 'health_check_url') ?? null : null,
+        stop_instruction: rawIntent ? readString(rawIntent, 'stop_instruction') ?? null : null,
+        related_oneshot_checks: readIntentStrings(rawIntent, 'related_oneshot_checks'),
+    };
+}
+function createCommandCatalogIntent(projectRoot, contract, name) {
+    let plan;
+    try {
+        plan = createRunPlan(projectRoot, contract, name);
+    }
+    catch (error) {
+        return createCommandCatalogIntentFromError(contract, name, error);
+    }
+    const rawIntent = isRecord(plan.intent) ? plan.intent : undefined;
+    return {
+        name,
+        description: rawIntent ? readString(rawIntent, 'description') ?? null : null,
+        kind: plan.kind,
+        status: plan.intentStatus,
+        lifecycle: plan.lifecycle,
+        run_policy: plan.runPolicy,
+        runnable: plan.ok,
+        reason_code: plan.reasonCode,
+        detail: plan.detail,
+        run_command: plan.ok ? commandForIntent('run', name) : null,
+        preview_command: commandForIntent('preview', name),
+        mode: plan.mode,
+        cwd: plan.relativeCwd,
+        timeout_seconds: plan.timeoutSeconds,
+        kill_after_seconds: plan.killAfterSeconds,
+        max_output_bytes: plan.maxOutputBytes,
+        success_exit_codes: plan.successExitCodes,
+        required_after: readIntentStrings(rawIntent, 'required_after'),
+        writes: plan.writes ?? [],
+        effect_count: plan.effects?.length ?? 0,
+        network: toNullableBoolean(plan.network),
+        destructive: toNullableBoolean(plan.destructive),
+        accepts_test_targets: acceptsTestTargets(rawIntent),
+        env_policy: plan.envPolicy,
+        env_allowlist: plan.envAllowlist,
+        precondition_count: plan.preconditions.length,
+        active_lock_conflict_count: plan.activeLockConflicts.length,
+        stale_active_lock_count: plan.staleActiveLocks.length,
+        agent_action: rawIntent ? readString(rawIntent, 'agent_action') ?? null : null,
+        manual_start_hint: plan.manualStartHint,
+        health_check_url: plan.healthCheckUrl,
+        stop_instruction: plan.stopInstruction,
+        related_oneshot_checks: plan.relatedOneshotChecks,
+    };
+}
+function createEmptyCommandCatalogContract(exists, parseError) {
+    return {
+        path: COMMANDS_RELATIVE_PATH,
+        exists,
+        parse_error: parseError,
+        total_intents: 0,
+        runnable_count: 0,
+        blocked_count: 0,
+    };
+}
+function createCommandCatalogOutputForRoot(mustflowRoot) {
+    const executionPolicy = {
+        command_authority: COMMANDS_RELATIVE_PATH,
+        run_entrypoint: 'mf run <intent>',
+        preview_entrypoint: 'mf run <intent> --dry-run --json',
+        direct_commands_allowed: false,
+        requires_configured_oneshot_agent_allowed: true,
+    };
+    if (!pathExists(mustflowRoot, COMMANDS_RELATIVE_PATH)) {
+        return {
+            schema_version: API_COMMAND_CATALOG_SCHEMA_VERSION,
+            command: 'api command-catalog',
+            mustflow_root: mustflowRoot,
+            command_contract: createEmptyCommandCatalogContract(false, null),
+            execution_policy: executionPolicy,
+            intents: [],
+            issues: [`${COMMANDS_RELATIVE_PATH} is missing.`],
+        };
+    }
+    let contract;
+    try {
+        contract = readCommandContract(mustflowRoot);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            schema_version: API_COMMAND_CATALOG_SCHEMA_VERSION,
+            command: 'api command-catalog',
+            mustflow_root: mustflowRoot,
+            command_contract: createEmptyCommandCatalogContract(true, message),
+            execution_policy: executionPolicy,
+            intents: [],
+            issues: [message],
+        };
+    }
+    const intents = Object.keys(contract.intents)
+        .sort((left, right) => left.localeCompare(right))
+        .map((name) => createCommandCatalogIntent(mustflowRoot, contract, name));
+    const runnableCount = intents.filter((intent) => intent.runnable).length;
+    return {
+        schema_version: API_COMMAND_CATALOG_SCHEMA_VERSION,
+        command: 'api command-catalog',
+        mustflow_root: mustflowRoot,
+        command_contract: {
+            path: COMMANDS_RELATIVE_PATH,
+            exists: true,
+            parse_error: null,
+            total_intents: intents.length,
+            runnable_count: runnableCount,
+            blocked_count: Math.max(0, intents.length - runnableCount),
+        },
+        execution_policy: executionPolicy,
+        intents,
+        issues: [],
+    };
+}
+function createCommandCatalogOutput() {
+    return createCommandCatalogOutputForRoot(resolveMustflowRoot());
+}
+function createWorkspaceSummaryOutput() {
+    const mustflowRoot = resolveMustflowRoot();
+    const context = getAgentContext(mustflowRoot);
+    const check = summarizeCheck(mustflowRoot);
+    const gitState = summarizeGitState(mustflowRoot);
+    const partialOutput = {
+        installed: context.installed,
+        check,
+        git_state: gitState,
+    };
+    return {
+        schema_version: API_WORKSPACE_SUMMARY_SCHEMA_VERSION,
+        command: 'api workspace-summary',
+        mustflow_root: context.mustflow_root,
+        installed: context.installed,
+        manifest_lock: context.manifest_lock,
+        template: context.template,
+        check,
+        read_order: summarizeReadOrder(context),
+        command_surface: summarizeCommandSurface(mustflowRoot, context),
+        skill_surface: summarizeSkillSurface(mustflowRoot),
+        git_state: gitState,
+        latest_run: context.latest_run,
+        effective_policy: context.effective_policy,
+        state_policy: context.state_policy,
+        blocked_actions: context.blocked_actions,
+        recommended_read_surfaces: createRecommendedReadSurfaces(context),
+        recommended_next_commands: createRecommendedNextCommands(partialOutput),
+        issues: context.issues,
+    };
+}
+function createVerificationPlanExecutionPolicy() {
+    return {
+        plan_command: 'mf verify --changed --plan-only --json',
+        run_command: 'mf verify --changed --json',
+        direct_commands_allowed: false,
+        selected_intents_run_via: 'mf run <intent>',
+    };
+}
+function createVerificationPlanSource() {
+    return {
+        kind: 'changed',
+        command: 'mf verify --changed --plan-only --json',
+    };
+}
+function toVerificationPlanClassification(output) {
+    return {
+        source: 'changed',
+        file_count: output.summary.fileCount,
+        files: output.files,
+        validation_reasons: output.summary.validationReasons,
+        public_surface_count: output.summary.publicSurfaceCount,
+        update_policies: output.summary.updatePolicies,
+        drift_checks: output.summary.driftChecks,
+    };
+}
+function toVerificationPlanRequirement(requirement) {
+    return {
+        reason: requirement.reason,
+        file_count: requirement.files.length,
+        files: requirement.files,
+        surfaces: requirement.surfaces,
+        affected_contracts: requirement.affectedContracts,
+        drift_checks: requirement.driftChecks,
+        update_policies: requirement.updatePolicies,
+    };
+}
+function toVerificationPlanSchedule(report) {
+    return {
+        runner: report.schedule.runner,
+        entry_count: report.schedule.entries.length,
+        batch_count: report.schedule.batches.length,
+        selected_intents: report.schedule.entries.map((entry) => entry.intent),
+        entries: report.schedule.entries.map((entry) => ({
+            intent: entry.intent,
+            run_command: commandForIntent('run', entry.intent),
+            preview_command: commandForIntent('preview', entry.intent),
+            parallel_eligible: entry.parallelEligible,
+            parallel_reason: entry.parallelReason,
+            locks: entry.locks,
+            conflict_count: entry.conflicts.length,
+        })),
+        batches: report.schedule.batches.map((batch) => ({
+            index: batch.index,
+            intents: batch.intents,
+            locks: batch.locks,
+        })),
+        notes: report.schedule.notes,
+    };
+}
+function toVerificationPlanTestSelection(report) {
+    return {
+        status: report.test_selection.status,
+        candidate_count: report.test_selection.matches.length,
+        selected_count: report.test_selection.selected.length,
+        note: report.test_selection.notes[0] ?? null,
+    };
+}
+function createUnavailableVerificationPlanOutput(mustflowRoot, classification, issue) {
+    return {
+        schema_version: API_VERIFICATION_PLAN_SCHEMA_VERSION,
+        command: 'api verification-plan',
+        mustflow_root: mustflowRoot,
+        source: createVerificationPlanSource(),
+        status: 'unavailable',
+        verification_plan_id: null,
+        classification: classification ? toVerificationPlanClassification(classification) : null,
+        requirements: [],
+        candidates: [],
+        gaps: [],
+        schedule: null,
+        test_selection: null,
+        execution_policy: createVerificationPlanExecutionPolicy(),
+        issues: [issue],
+    };
+}
+function createVerificationPlanOutput() {
+    const mustflowRoot = resolveMustflowRoot();
+    let classification = null;
+    try {
+        classification = createClassifyOutput(mustflowRoot, 'changed', []);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return createUnavailableVerificationPlanOutput(mustflowRoot, null, message);
+    }
+    let contract;
+    try {
+        contract = readCommandContract(mustflowRoot);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return createUnavailableVerificationPlanOutput(mustflowRoot, classification, message);
+    }
+    let report;
+    try {
+        report = createChangeVerificationReport(classification, contract, mustflowRoot);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return createUnavailableVerificationPlanOutput(mustflowRoot, classification, message);
+    }
+    return {
+        schema_version: API_VERIFICATION_PLAN_SCHEMA_VERSION,
+        command: 'api verification-plan',
+        mustflow_root: mustflowRoot,
+        source: createVerificationPlanSource(),
+        status: 'available',
+        verification_plan_id: createVerificationPlanId(report, contract),
+        classification: toVerificationPlanClassification(classification),
+        requirements: report.requirements.map(toVerificationPlanRequirement),
+        candidates: report.candidates.map((candidate) => ({
+            reason: candidate.reason,
+            intent: candidate.intent,
+            status: candidate.status,
+            selection_state: candidate.selectionState,
+            eligibility_state: candidate.eligibilityState,
+            candidate_state: candidate.candidateState,
+            skip_reason: candidate.skipReason,
+            detail: candidate.detail,
+        })),
+        gaps: report.gaps.map((gap) => ({
+            reason: gap.reason,
+            files: gap.files,
+            surfaces: gap.surfaces,
+            detail: gap.detail,
+        })),
+        schedule: toVerificationPlanSchedule(report),
+        test_selection: toVerificationPlanTestSelection(report),
+        execution_policy: createVerificationPlanExecutionPolicy(),
+        issues: [],
+    };
+}
+function readJsonInsideRoot(projectRoot, relativePath) {
+    return JSON.parse(readUtf8FileInsideWithoutSymlinks(projectRoot, path.join(projectRoot, ...relativePath.split('/')), {
+        maxBytes: MUSTFLOW_JSON_MAX_BYTES,
+    }));
+}
+function readLatestEvidenceManifest(projectRoot, latest) {
+    if (latest.kind !== 'verify_run_summary' || !latest.manifest_path) {
+        return {
+            status: 'not_applicable',
+            path: null,
+            receipt_count: null,
+            error: null,
+        };
+    }
+    try {
+        const manifest = readJsonInsideRoot(projectRoot, latest.manifest_path);
+        const receiptCount = isRecord(manifest) && Array.isArray(manifest.receipts) ? manifest.receipts.length : null;
+        return {
+            status: receiptCount === null ? 'unavailable' : 'available',
+            path: latest.manifest_path,
+            receipt_count: receiptCount,
+            error: receiptCount === null ? 'Verify manifest is not a recognized manifest object.' : null,
+        };
+    }
+    catch (error) {
+        return {
+            status: 'unavailable',
+            path: latest.manifest_path,
+            receipt_count: null,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function latestEvidenceSummaryFromParsed(parsed) {
+    if (!isRecord(parsed)) {
+        return {
+            exists: true,
+            path: LATEST_RUN_RELATIVE_PATH,
+            kind: 'unknown',
+            status: null,
+            intent: null,
+            reason: null,
+            verification_plan_id: null,
+            completion_verdict_status: null,
+            manifest_path: null,
+            receipt_path: null,
+            run_dir: null,
+            exit_code: null,
+            timed_out: null,
+            duration_ms: null,
+            summary: null,
+        };
+    }
+    const command = readString(parsed, 'command');
+    const kind = command === 'run'
+        ? 'run_receipt'
+        : command === 'verify' && readString(parsed, 'kind') === 'verify_run_summary'
+            ? 'verify_run_summary'
+            : 'unknown';
+    const completionVerdict = isRecord(parsed.completion_verdict) ? parsed.completion_verdict : null;
+    return {
+        exists: true,
+        path: LATEST_RUN_RELATIVE_PATH,
+        kind,
+        status: readString(parsed, 'status') ?? null,
+        intent: readString(parsed, 'intent') ?? null,
+        reason: readString(parsed, 'reason') ?? null,
+        verification_plan_id: readString(parsed, 'verification_plan_id') ?? null,
+        completion_verdict_status: completionVerdict ? readString(completionVerdict, 'status') ?? null : null,
+        manifest_path: readString(parsed, 'manifest_path') ?? null,
+        receipt_path: readString(parsed, 'receipt_path') ?? null,
+        run_dir: readString(parsed, 'run_dir') ?? null,
+        exit_code: typeof parsed.exit_code === 'number' ? parsed.exit_code : null,
+        timed_out: typeof parsed.timed_out === 'boolean' ? parsed.timed_out : null,
+        duration_ms: typeof parsed.duration_ms === 'number' ? parsed.duration_ms : null,
+        summary: isRecord(parsed.summary) ? parsed.summary : null,
+    };
+}
+function createLatestEvidenceOutput() {
+    const mustflowRoot = resolveMustflowRoot();
+    const issues = [];
+    let latest;
+    try {
+        latest = latestEvidenceSummaryFromParsed(readJsonInsideRoot(mustflowRoot, LATEST_RUN_RELATIVE_PATH));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        latest = {
+            exists: false,
+            path: LATEST_RUN_RELATIVE_PATH,
+            kind: null,
+            status: null,
+            intent: null,
+            reason: null,
+            verification_plan_id: null,
+            completion_verdict_status: null,
+            manifest_path: null,
+            receipt_path: null,
+            run_dir: null,
+            exit_code: null,
+            timed_out: null,
+            duration_ms: null,
+            summary: null,
+        };
+        if (!message.includes('ENOENT')) {
+            issues.push(message);
+        }
+    }
+    return {
+        schema_version: API_LATEST_EVIDENCE_SCHEMA_VERSION,
+        command: 'api latest-evidence',
+        mustflow_root: mustflowRoot,
+        latest,
+        manifest: readLatestEvidenceManifest(mustflowRoot, latest),
+        policy: {
+            raw_output_included: false,
+            hidden_reasoning_included: false,
+            max_bytes: MUSTFLOW_JSON_MAX_BYTES,
+        },
+        issues,
+    };
+}
+function getRiskLevel(classification, report) {
+    if (!classification || !report) {
+        return 'unknown';
+    }
+    if (classification.summary.fileCount === 0) {
+        return 'none';
+    }
+    const reasons = new Set(classification.summary.validationReasons);
+    if (report.gaps.length > 0 ||
+        classification.summary.publicSurfaceCount > 0 ||
+        reasons.has('release_risk') ||
+        reasons.has('package_metadata_change') ||
+        reasons.has('mustflow_config_change') ||
+        reasons.has('mustflow_docs_change')) {
+        return 'high';
+    }
+    if (reasons.has('code_change') || reasons.has('behavior_change') || reasons.has('test_change') || reasons.has('unknown_change')) {
+        return 'medium';
+    }
+    return 'low';
+}
+function createDiffRiskOutput() {
+    const mustflowRoot = resolveMustflowRoot();
+    let classification = null;
+    try {
+        classification = createClassifyOutput(mustflowRoot, 'changed', []);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            schema_version: API_DIFF_RISK_SCHEMA_VERSION,
+            command: 'api diff-risk',
+            mustflow_root: mustflowRoot,
+            source: createVerificationPlanSource(),
+            status: 'unavailable',
+            risk_level: 'unknown',
+            changed_file_count: 0,
+            changed_files: [],
+            public_surface_count: 0,
+            validation_reasons: [],
+            update_policies: [],
+            drift_checks: [],
+            required_verification: [],
+            gap_count: 0,
+            gaps: [],
+            recommended_commands: [],
+            issues: [message],
+        };
+    }
+    let report = null;
+    const issues = [];
+    try {
+        report = createChangeVerificationReport(classification, readCommandContract(mustflowRoot), mustflowRoot);
+    }
+    catch (error) {
+        issues.push(error instanceof Error ? error.message : String(error));
+    }
+    const requiredVerification = report ? report.schedule.entries.map((entry) => entry.intent) : [];
+    return {
+        schema_version: API_DIFF_RISK_SCHEMA_VERSION,
+        command: 'api diff-risk',
+        mustflow_root: mustflowRoot,
+        source: createVerificationPlanSource(),
+        status: report ? 'available' : 'unavailable',
+        risk_level: getRiskLevel(classification, report),
+        changed_file_count: classification.summary.fileCount,
+        changed_files: classification.files,
+        public_surface_count: classification.summary.publicSurfaceCount,
+        validation_reasons: classification.summary.validationReasons,
+        update_policies: classification.summary.updatePolicies,
+        drift_checks: classification.summary.driftChecks,
+        required_verification: requiredVerification,
+        gap_count: report?.gaps.length ?? 0,
+        gaps: report?.gaps.map((gap) => ({
+            reason: gap.reason,
+            files: gap.files,
+            surfaces: gap.surfaces,
+            detail: gap.detail,
+        })) ?? [],
+        recommended_commands: [
+            'mf api verification-plan --changed --json',
+            ...(requiredVerification.length > 0 ? ['mf verify --changed --json'] : []),
+        ],
+        issues,
+    };
+}
+function createHealthOutput() {
+    const workspace = createWorkspaceSummaryOutput();
+    const catalog = createCommandCatalogOutputForRoot(workspace.mustflow_root);
+    const blockers = [
+        ...workspace.check.issues,
+        ...catalog.issues,
+    ];
+    const warnings = [
+        ...workspace.check.warnings,
+        ...(workspace.git_state.status === 'unavailable' && workspace.git_state.error ? [workspace.git_state.error] : []),
+    ];
+    const commandContractOk = catalog.command_contract.exists && catalog.command_contract.parse_error === null;
+    const status = blockers.length > 0 || !workspace.installed || !commandContractOk
+        ? 'blocked'
+        : warnings.length > 0
+            ? 'degraded'
+            : 'ok';
+    return {
+        schema_version: API_HEALTH_SCHEMA_VERSION,
+        command: 'api health',
+        mustflow_root: workspace.mustflow_root,
+        status,
+        installed: workspace.installed,
+        check_ok: workspace.check.ok,
+        command_contract_ok: commandContractOk,
+        runnable_count: catalog.command_contract.runnable_count,
+        git_status: workspace.git_state.status,
+        changed_file_count: workspace.git_state.changed_file_count,
+        latest_run_exists: workspace.latest_run.exists,
+        blockers,
+        warnings,
+        recommended_next_commands: workspace.recommended_next_commands,
+    };
+}
+function validateJsonOnlyAction(action, args, reporter, lang) {
+    if (args.includes('--help') || args.includes('-h')) {
+        reporter.stdout(getApiHelp(lang));
+        return false;
+    }
+    const supported = new Set(['--json']);
+    const unsupported = args.filter((arg) => !supported.has(arg));
+    if (unsupported.length > 0) {
+        printUsageError(reporter, t(lang, 'cli.error.unknownOption', { option: unsupported[0] }), 'mf api --help', getApiHelp(lang), lang);
+        return false;
+    }
+    if (!args.includes('--json')) {
+        printUsageError(reporter, t(lang, 'api.error.actionRequiresJson', { action }), 'mf api --help', getApiHelp(lang), lang);
+        return false;
+    }
+    return true;
+}
+function runWorkspaceSummary(args, reporter, lang) {
+    if (!validateJsonOnlyAction('workspace-summary', args, reporter, lang)) {
+        return args.includes('--help') || args.includes('-h') ? 0 : 1;
+    }
+    reporter.stdout(JSON.stringify(createWorkspaceSummaryOutput(), null, 2));
+    return 0;
+}
+function runCommandCatalog(args, reporter, lang) {
+    if (!validateJsonOnlyAction('command-catalog', args, reporter, lang)) {
+        return args.includes('--help') || args.includes('-h') ? 0 : 1;
+    }
+    reporter.stdout(JSON.stringify(createCommandCatalogOutput(), null, 2));
+    return 0;
+}
+function validateChangedJsonAction(action, args, reporter, lang) {
+    if (args.includes('--help') || args.includes('-h')) {
+        reporter.stdout(getApiHelp(lang));
+        return false;
+    }
+    const supported = new Set(['--changed', '--json']);
+    const unsupported = args.filter((arg) => !supported.has(arg));
+    if (unsupported.length > 0) {
+        printUsageError(reporter, t(lang, 'cli.error.unknownOption', { option: unsupported[0] }), 'mf api --help', getApiHelp(lang), lang);
+        return false;
+    }
+    if (!args.includes('--json')) {
+        printUsageError(reporter, t(lang, 'api.error.actionRequiresJson', { action }), 'mf api --help', getApiHelp(lang), lang);
+        return false;
+    }
+    if (!args.includes('--changed')) {
+        printUsageError(reporter, t(lang, 'api.error.actionRequiresChanged', { action }), 'mf api --help', getApiHelp(lang), lang);
+        return false;
+    }
+    return true;
+}
+function runVerificationPlan(args, reporter, lang) {
+    if (!validateChangedJsonAction('verification-plan', args, reporter, lang)) {
+        return args.includes('--help') || args.includes('-h') ? 0 : 1;
+    }
+    reporter.stdout(JSON.stringify(createVerificationPlanOutput(), null, 2));
+    return 0;
+}
+function runLatestEvidence(args, reporter, lang) {
+    if (!validateJsonOnlyAction('latest-evidence', args, reporter, lang)) {
+        return args.includes('--help') || args.includes('-h') ? 0 : 1;
+    }
+    reporter.stdout(JSON.stringify(createLatestEvidenceOutput(), null, 2));
+    return 0;
+}
+function runDiffRisk(args, reporter, lang) {
+    if (!validateChangedJsonAction('diff-risk', args, reporter, lang)) {
+        return args.includes('--help') || args.includes('-h') ? 0 : 1;
+    }
+    reporter.stdout(JSON.stringify(createDiffRiskOutput(), null, 2));
+    return 0;
+}
+function runHealth(args, reporter, lang) {
+    if (!validateJsonOnlyAction('health', args, reporter, lang)) {
+        return args.includes('--help') || args.includes('-h') ? 0 : 1;
+    }
+    reporter.stdout(JSON.stringify(createHealthOutput(), null, 2));
+    return 0;
+}
+export function runApi(args, reporter, lang = 'en') {
+    if (args.includes('--help') || args.includes('-h')) {
+        reporter.stdout(getApiHelp(lang));
+        return 0;
+    }
+    const [action, ...rest] = args;
+    if (!action) {
+        printUsageError(reporter, t(lang, 'api.error.missingAction'), 'mf api --help', getApiHelp(lang), lang);
+        return 1;
+    }
+    if (action.startsWith('-')) {
+        printUsageError(reporter, t(lang, 'cli.error.unknownOption', { option: action }), 'mf api --help', getApiHelp(lang), lang);
+        return 1;
+    }
+    if (action === 'workspace-summary') {
+        return runWorkspaceSummary(rest, reporter, lang);
+    }
+    if (action === 'command-catalog') {
+        return runCommandCatalog(rest, reporter, lang);
+    }
+    if (action === 'verification-plan') {
+        return runVerificationPlan(rest, reporter, lang);
+    }
+    if (action === 'latest-evidence') {
+        return runLatestEvidence(rest, reporter, lang);
+    }
+    if (action === 'diff-risk') {
+        return runDiffRisk(rest, reporter, lang);
+    }
+    if (action === 'health') {
+        return runHealth(rest, reporter, lang);
+    }
+    printUsageError(reporter, t(lang, 'api.error.unknownAction', { action }), 'mf api --help', getApiHelp(lang), lang);
+    return 1;
+}