mustflow 2.22.17 → 2.22.47

package/dist/core/validation-ratchet.js

@@ -2,6 +2,8 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { createCommandEnv } from './command-env.js';
+const GIT_DIFF_TIMEOUT_MS = 10_000;
+const GIT_DIFF_MAX_BUFFER_BYTES = 16 * 1024 * 1024;
 const TEST_CHANGE_KINDS = new Set(['test', 'test_fixture']);
 const SKIP_OR_ONLY_MARKER = /\b(?:describe|it|test)\s*\.\s*(?:skip|only)\s*\(/u;
 const TODO_OR_PENDING_MARKER = /\b(?:describe|it|test)\s*\.\s*(?:todo|pending)\s*\(/u;
@@ -49,30 +51,66 @@ function fileTextIfReadable(projectRoot, relativePath) {
         return null;
     }
 }
-function gitDiffLines(projectRoot, relativePath) {
-    const result = spawnSync('git', ['diff', '--no-ext-diff', '--unified=0', '--', relativePath], {
-        cwd: projectRoot,
-        encoding: 'utf8',
-        env: createCommandEnv(projectRoot, { policy: 'minimal', allowlist: [] }),
-        windowsHide: true,
-    });
-    if (result.status !== 0 || typeof result.stdout !== 'string' || result.stdout.length === 0) {
-        return { added: [], removed: [] };
-    }
-    const added = [];
-    const removed = [];
-    for (const line of result.stdout.split(/\r?\n/u)) {
-        if (line.startsWith('+++') || line.startsWith('---')) {
+function normalizeGitDiffPath(value) {
+    return value
+        .replace(/^"(.*)"$/u, '$1')
+        .replace(/^(?:a|b)\//u, '')
+        .replaceAll('\\', '/');
+}
+function parseGitDiffLines(stdout) {
+    const byPath = new Map();
+    let oldPath = null;
+    let currentPath = null;
+    for (const line of stdout.split(/\r?\n/u)) {
+        if (line.startsWith('--- ')) {
+            const rawPath = line.slice(4).trim();
+            oldPath = rawPath === '/dev/null' ? null : normalizeGitDiffPath(rawPath);
+            continue;
+        }
+        if (line.startsWith('+++ ')) {
+            const rawPath = line.slice(4).trim();
+            currentPath = rawPath === '/dev/null' ? oldPath : normalizeGitDiffPath(rawPath);
+            if (currentPath && !byPath.has(currentPath)) {
+                byPath.set(currentPath, { added: [], removed: [] });
+            }
+            continue;
+        }
+        if (!currentPath || line.startsWith('@@')) {
+            continue;
+        }
+        const diff = byPath.get(currentPath);
+        if (!diff) {
             continue;
         }
         if (line.startsWith('+')) {
-            added.push(line.slice(1));
+            diff.added.push(line.slice(1));
         }
         else if (line.startsWith('-')) {
-            removed.push(line.slice(1));
+            diff.removed.push(line.slice(1));
         }
     }
-    return { added, removed };
+    return new Map([...byPath.entries()].map(([filePath, diff]) => [
+        filePath,
+        { added: diff.added, removed: diff.removed },
+    ]));
+}
+function gitDiffLinesByPath(projectRoot, relativePaths) {
+    const uniquePaths = [...new Set(relativePaths)].filter((relativePath) => resolveInsideRoot(projectRoot, relativePath) !== null);
+    if (uniquePaths.length === 0) {
+        return new Map();
+    }
+    const result = spawnSync('git', ['diff', '--no-ext-diff', '--unified=0', '--', ...uniquePaths], {
+        cwd: projectRoot,
+        encoding: 'utf8',
+        env: createCommandEnv(projectRoot, { policy: 'minimal', allowlist: [] }),
+        maxBuffer: GIT_DIFF_MAX_BUFFER_BYTES,
+        timeout: GIT_DIFF_TIMEOUT_MS,
+        windowsHide: true,
+    });
+    if (result.status !== 0 || typeof result.stdout !== 'string' || result.stdout.length === 0) {
+        return new Map();
+    }
+    return parseGitDiffLines(result.stdout);
 }
 function countMatching(lines, pattern) {
     return lines.filter((line) => pattern.test(line)).length;
@@ -105,6 +143,9 @@ export function countValidationRatchetVerdictEffects(risks) {
 export function createValidationRatchetRisks(report, projectRoot) {
     const risks = [];
     const seenRisks = new Set();
+    const changedDiffs = report.source === 'changed'
+        ? gitDiffLinesByPath(projectRoot, report.classifications.map((classification) => classification.path))
+        : new Map();
     function addRisk(code, severity, pathText, detail) {
         const key = `${pathText}\0${code}`;
         if (seenRisks.has(key)) {
@@ -115,7 +156,9 @@ export function createValidationRatchetRisks(report, projectRoot) {
     }
     for (const classification of report.classifications) {
         const resolvedPath = resolveInsideRoot(projectRoot, classification.path);
-        const diff = report.source === 'changed' ? gitDiffLines(projectRoot, classification.path) : { added: [], removed: [] };
+        const diff = report.source === 'changed'
+            ? changedDiffs.get(classification.path) ?? { added: [], removed: [] }
+            : { added: [], removed: [] };
         const addedText = diff.added.join('\n');
         if (isTestClassification(classification)) {
             if (report.source === 'changed' && (resolvedPath === null || !existsSync(resolvedPath))) {

package/dist/core/verification-decision-graph.js

@@ -1,7 +1,14 @@
+import { createHash } from 'node:crypto';
 import { isRecord, readString, readStringArray, } from './config-loading.js';
 export const VERIFICATION_DECISION_GRAPH_SCHEMA_VERSION = '1';
 function stableIdPart(value) {
-    return value.trim().replace(/[^A-Za-z0-9_.-]+/gu, '_') || 'none';
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        return 'none';
+    }
+    const readable = trimmed.replace(/[^A-Za-z0-9_.-]+/gu, '_') || 'value';
+    const digest = createHash('sha256').update(trimmed).digest('hex').slice(0, 10);
+    return `${readable}_${digest}`;
 }
 function readBoolean(table, key) {
     const value = table[key];

package/dist/core/verification-plan-id.js

@@ -0,0 +1,44 @@
+import { createHash } from 'node:crypto';
+function hashTextSha256(content) {
+    return `sha256:${createHash('sha256').update(content).digest('hex')}`;
+}
+function stableJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => stableJson(entry)).join(',')}]`;
+    }
+    if (value && typeof value === 'object') {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort((left, right) => left.localeCompare(right))
+            .map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+function getCandidateIntentNames(report) {
+    return [...new Set(report.candidates.map((candidate) => candidate.intent).filter((intent) => Boolean(intent)))]
+        .sort((left, right) => left.localeCompare(right));
+}
+export function createVerificationPlanId(report, contract) {
+    const relatedIntents = Object.fromEntries(getCandidateIntentNames(report).map((intent) => [intent, contract.intents[intent] ?? null]));
+    const fingerprintSource = {
+        schema_version: '1',
+        algorithm: 'mustflow.verify_plan_id.v1',
+        report: {
+            source: report.source,
+            files: report.files,
+            classification_summary: report.classification_summary,
+            requirements: report.requirements,
+            candidates: report.candidates,
+            gaps: report.gaps,
+            schedule: report.schedule,
+            test_selection: report.test_selection,
+        },
+        command_contract: {
+            defaults: contract.defaults,
+            resources: contract.resources,
+            intents: relatedIntents,
+        },
+    };
+    return hashTextSha256(stableJson(fingerprintSource));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "2.22.17",
+  "version": "2.22.47",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",

package/schemas/README.md

@@ -8,6 +8,12 @@ Current schemas:
 - `doctor-report.schema.json`: output of `mf doctor --json`
 - `adapter-compatibility-report.schema.json`: output of `mf adapters status --json`
 - `context-report.schema.json`: output of `mf context --json`
+- `workspace-summary.schema.json`: output of `mf api workspace-summary --json`
+- `command-catalog.schema.json`: output of `mf api command-catalog --json`
+- `verification-plan.schema.json`: output of `mf api verification-plan --changed --json`
+- `latest-evidence.schema.json`: output of `mf api latest-evidence --json`
+- `diff-risk.schema.json`: output of `mf api diff-risk --changed --json`
+- `health.schema.json`: output of `mf api health --json`
 - `run-receipt.schema.json`: output of `mf run <intent> --json` and `.mustflow/state/runs/latest.json`,
   including bounded declared-write drift metadata, a safe latest-run performance summary, and optional
   structured phase timings and selection summaries

package/schemas/command-catalog.schema.json

@@ -0,0 +1,158 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/command-catalog.schema.json",
+  "title": "mustflow command catalog API report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "mustflow_root",
+    "command_contract",
+    "execution_policy",
+    "intents",
+    "issues"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "api command-catalog" },
+    "mustflow_root": { "type": "string" },
+    "command_contract": { "$ref": "#/$defs/commandContract" },
+    "execution_policy": { "$ref": "#/$defs/executionPolicy" },
+    "intents": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/intent" }
+    },
+    "issues": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  },
+  "$defs": {
+    "commandContract": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "exists", "parse_error", "total_intents", "runnable_count", "blocked_count"],
+      "properties": {
+        "path": { "const": ".mustflow/config/commands.toml" },
+        "exists": { "type": "boolean" },
+        "parse_error": { "type": ["string", "null"] },
+        "total_intents": { "type": "integer", "minimum": 0 },
+        "runnable_count": { "type": "integer", "minimum": 0 },
+        "blocked_count": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "executionPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "command_authority",
+        "run_entrypoint",
+        "preview_entrypoint",
+        "direct_commands_allowed",
+        "requires_configured_oneshot_agent_allowed"
+      ],
+      "properties": {
+        "command_authority": { "const": ".mustflow/config/commands.toml" },
+        "run_entrypoint": { "const": "mf run <intent>" },
+        "preview_entrypoint": { "const": "mf run <intent> --dry-run --json" },
+        "direct_commands_allowed": { "const": false },
+        "requires_configured_oneshot_agent_allowed": { "const": true }
+      }
+    },
+    "intent": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "description",
+        "kind",
+        "status",
+        "lifecycle",
+        "run_policy",
+        "runnable",
+        "reason_code",
+        "detail",
+        "run_command",
+        "preview_command",
+        "mode",
+        "cwd",
+        "timeout_seconds",
+        "kill_after_seconds",
+        "max_output_bytes",
+        "success_exit_codes",
+        "required_after",
+        "writes",
+        "effect_count",
+        "network",
+        "destructive",
+        "accepts_test_targets",
+        "env_policy",
+        "env_allowlist",
+        "precondition_count",
+        "active_lock_conflict_count",
+        "stale_active_lock_count",
+        "agent_action",
+        "manual_start_hint",
+        "health_check_url",
+        "stop_instruction",
+        "related_oneshot_checks"
+      ],
+      "properties": {
+        "name": { "type": "string" },
+        "description": { "type": ["string", "null"] },
+        "kind": { "type": ["string", "null"] },
+        "status": { "type": ["string", "null"] },
+        "lifecycle": { "type": ["string", "null"] },
+        "run_policy": { "type": ["string", "null"] },
+        "runnable": { "type": "boolean" },
+        "reason_code": { "type": ["string", "null"] },
+        "detail": { "type": ["string", "null"] },
+        "run_command": { "type": ["string", "null"] },
+        "preview_command": { "type": ["string", "null"] },
+        "mode": { "enum": ["argv", "shell", null] },
+        "cwd": { "type": ["string", "null"] },
+        "timeout_seconds": { "type": ["integer", "null"], "minimum": 1 },
+        "kill_after_seconds": { "type": ["integer", "null"], "minimum": 1 },
+        "max_output_bytes": { "type": ["integer", "null"], "minimum": 1 },
+        "success_exit_codes": {
+          "anyOf": [
+            { "type": "null" },
+            {
+              "type": "array",
+              "items": { "type": "integer", "minimum": 0 }
+            }
+          ]
+        },
+        "required_after": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "writes": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "effect_count": { "type": "integer", "minimum": 0 },
+        "network": { "type": ["boolean", "null"] },
+        "destructive": { "type": ["boolean", "null"] },
+        "accepts_test_targets": { "type": "boolean" },
+        "env_policy": { "type": ["string", "null"] },
+        "env_allowlist": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "precondition_count": { "type": "integer", "minimum": 0 },
+        "active_lock_conflict_count": { "type": "integer", "minimum": 0 },
+        "stale_active_lock_count": { "type": "integer", "minimum": 0 },
+        "agent_action": { "type": ["string", "null"] },
+        "manual_start_hint": { "type": ["string", "null"] },
+        "health_check_url": { "type": ["string", "null"] },
+        "stop_instruction": { "type": ["string", "null"] },
+        "related_oneshot_checks": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/schemas/diff-risk.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/diff-risk.schema.json",
+  "title": "mustflow diff risk API report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "mustflow_root",
+    "source",
+    "status",
+    "risk_level",
+    "changed_file_count",
+    "changed_files",
+    "public_surface_count",
+    "validation_reasons",
+    "update_policies",
+    "drift_checks",
+    "required_verification",
+    "gap_count",
+    "gaps",
+    "recommended_commands",
+    "issues"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "api diff-risk" },
+    "mustflow_root": { "type": "string" },
+    "source": { "$ref": "#/$defs/source" },
+    "status": { "enum": ["available", "unavailable"] },
+    "risk_level": { "enum": ["none", "low", "medium", "high", "unknown"] },
+    "changed_file_count": { "type": "integer", "minimum": 0 },
+    "changed_files": { "$ref": "#/$defs/stringArray" },
+    "public_surface_count": { "type": "integer", "minimum": 0 },
+    "validation_reasons": { "$ref": "#/$defs/stringArray" },
+    "update_policies": { "$ref": "#/$defs/stringArray" },
+    "drift_checks": { "$ref": "#/$defs/stringArray" },
+    "required_verification": { "$ref": "#/$defs/stringArray" },
+    "gap_count": { "type": "integer", "minimum": 0 },
+    "gaps": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/gap" }
+    },
+    "recommended_commands": { "$ref": "#/$defs/stringArray" },
+    "issues": { "$ref": "#/$defs/stringArray" }
+  },
+  "$defs": {
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "command"],
+      "properties": {
+        "kind": { "const": "changed" },
+        "command": { "const": "mf verify --changed --plan-only --json" }
+      }
+    },
+    "stringArray": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "gap": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["reason", "files", "surfaces", "detail"],
+      "properties": {
+        "reason": { "type": "string" },
+        "files": { "$ref": "#/$defs/stringArray" },
+        "surfaces": { "$ref": "#/$defs/stringArray" },
+        "detail": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/health.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/health.schema.json",
+  "title": "mustflow health API report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "mustflow_root",
+    "status",
+    "installed",
+    "check_ok",
+    "command_contract_ok",
+    "runnable_count",
+    "git_status",
+    "changed_file_count",
+    "latest_run_exists",
+    "blockers",
+    "warnings",
+    "recommended_next_commands"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "api health" },
+    "mustflow_root": { "type": "string" },
+    "status": { "enum": ["ok", "degraded", "blocked"] },
+    "installed": { "type": "boolean" },
+    "check_ok": { "type": "boolean" },
+    "command_contract_ok": { "type": "boolean" },
+    "runnable_count": { "type": "integer", "minimum": 0 },
+    "git_status": { "enum": ["available", "unavailable"] },
+    "changed_file_count": { "type": ["integer", "null"], "minimum": 0 },
+    "latest_run_exists": { "type": "boolean" },
+    "blockers": { "$ref": "#/$defs/stringArray" },
+    "warnings": { "$ref": "#/$defs/stringArray" },
+    "recommended_next_commands": { "$ref": "#/$defs/stringArray" }
+  },
+  "$defs": {
+    "stringArray": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

package/schemas/latest-evidence.schema.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/latest-evidence.schema.json",
+  "title": "mustflow latest evidence API report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "mustflow_root",
+    "latest",
+    "manifest",
+    "policy",
+    "issues"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "api latest-evidence" },
+    "mustflow_root": { "type": "string" },
+    "latest": { "$ref": "#/$defs/latest" },
+    "manifest": { "$ref": "#/$defs/manifest" },
+    "policy": { "$ref": "#/$defs/policy" },
+    "issues": { "$ref": "#/$defs/stringArray" }
+  },
+  "$defs": {
+    "stringArray": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "latest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "exists",
+        "path",
+        "kind",
+        "status",
+        "intent",
+        "reason",
+        "verification_plan_id",
+        "completion_verdict_status",
+        "manifest_path",
+        "receipt_path",
+        "run_dir",
+        "exit_code",
+        "timed_out",
+        "duration_ms",
+        "summary"
+      ],
+      "properties": {
+        "exists": { "type": "boolean" },
+        "path": { "const": ".mustflow/state/runs/latest.json" },
+        "kind": { "enum": ["run_receipt", "verify_run_summary", "unknown", null] },
+        "status": { "type": ["string", "null"] },
+        "intent": { "type": ["string", "null"] },
+        "reason": { "type": ["string", "null"] },
+        "verification_plan_id": { "type": ["string", "null"] },
+        "completion_verdict_status": { "type": ["string", "null"] },
+        "manifest_path": { "type": ["string", "null"] },
+        "receipt_path": { "type": ["string", "null"] },
+        "run_dir": { "type": ["string", "null"] },
+        "exit_code": { "type": ["integer", "null"] },
+        "timed_out": { "type": ["boolean", "null"] },
+        "duration_ms": { "type": ["integer", "null"], "minimum": 0 },
+        "summary": {
+          "anyOf": [
+            { "type": "null" },
+            { "type": "object" }
+          ]
+        }
+      }
+    },
+    "manifest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "path", "receipt_count", "error"],
+      "properties": {
+        "status": { "enum": ["available", "missing", "unavailable", "not_applicable"] },
+        "path": { "type": ["string", "null"] },
+        "receipt_count": { "type": ["integer", "null"], "minimum": 0 },
+        "error": { "type": ["string", "null"] }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["raw_output_included", "hidden_reasoning_included", "max_bytes"],
+      "properties": {
+        "raw_output_included": { "const": false },
+        "hidden_reasoning_included": { "const": false },
+        "max_bytes": { "type": "integer", "minimum": 1 }
+      }
+    }
+  }
+}