mustflow 1.15.97

package/dist/core/command-contract-validation.js

@@ -0,0 +1,197 @@
+import { COMMAND_LIFECYCLES, COMMAND_RUN_POLICIES, LONG_RUNNING_LIFECYCLES, isRecord, } from './config-loading.js';
+import { COMMAND_EFFECT_CONCURRENCY, COMMAND_EFFECT_MODES, COMMAND_EFFECT_TYPES, validateCommandEffectLockWarnings, validateCommandEffects, } from './command-effects.js';
+import { commandIntentHasBlockedShellBackgroundPattern, commandIntentHasCommandSource, commandIntentNameIsSafe, } from './command-contract-rules.js';
+function commandContractIssue(message) {
+    return { message };
+}
+function hasOwn(table, key) {
+    return Object.prototype.hasOwnProperty.call(table, key);
+}
+function isPositiveInteger(value) {
+    return Number.isInteger(value) && Number(value) > 0;
+}
+function validateTable(config, tableName, issues) {
+    if (!hasOwn(config, tableName)) {
+        return undefined;
+    }
+    const table = config[tableName];
+    if (!isRecord(table)) {
+        issues.push(commandContractIssue(`[${tableName}] must be a TOML table`));
+        return undefined;
+    }
+    return table;
+}
+function validateBooleanField(table, key, label, issues) {
+    if (hasOwn(table, key) && typeof table[key] !== 'boolean') {
+        issues.push(commandContractIssue(`${label} must be a boolean`));
+    }
+}
+function validateStringField(table, key, label, issues) {
+    if (hasOwn(table, key) && (typeof table[key] !== 'string' || table[key].trim().length === 0)) {
+        issues.push(commandContractIssue(`${label} must be a string`));
+    }
+}
+function validatePositiveIntegerField(table, key, label, issues) {
+    if (hasOwn(table, key) && !isPositiveInteger(table[key])) {
+        issues.push(commandContractIssue(`${label} must be a positive integer`));
+    }
+}
+function validateAllowedStringField(table, key, label, allowedValues, issues) {
+    if (!hasOwn(table, key)) {
+        return;
+    }
+    if (typeof table[key] !== 'string' || !allowedValues.has(table[key])) {
+        issues.push(commandContractIssue(`${label} must be ${Array.from(allowedValues).map((value) => `"${value}"`).join(' or ')}`));
+    }
+}
+function validateCommandDefaults(commandsToml, issues) {
+    const defaults = validateTable(commandsToml, 'defaults', issues);
+    if (!defaults) {
+        return;
+    }
+    validateStringField(defaults, 'missing_behavior', '[commands.defaults].missing_behavior', issues);
+    validateBooleanField(defaults, 'allow_inferred_commands', '[commands.defaults].allow_inferred_commands', issues);
+    validateBooleanField(defaults, 'require_lifecycle', '[commands.defaults].require_lifecycle', issues);
+    validateBooleanField(defaults, 'require_timeout_for_oneshot', '[commands.defaults].require_timeout_for_oneshot', issues);
+    validateBooleanField(defaults, 'deny_unmanaged_long_running', '[commands.defaults].deny_unmanaged_long_running', issues);
+    validateStringField(defaults, 'default_cwd', '[commands.defaults].default_cwd', issues);
+    validateStringField(defaults, 'stdin', '[commands.defaults].stdin', issues);
+    validateStringField(defaults, 'on_timeout', '[commands.defaults].on_timeout', issues);
+    validatePositiveIntegerField(defaults, 'default_timeout_seconds', '[commands.defaults].default_timeout_seconds', issues);
+    validatePositiveIntegerField(defaults, 'max_output_bytes', '[commands.defaults].max_output_bytes', issues);
+    validatePositiveIntegerField(defaults, 'kill_after_seconds', '[commands.defaults].kill_after_seconds', issues);
+}
+function validateCommandResources(commandsToml, issues) {
+    if (!hasOwn(commandsToml, 'resources')) {
+        return;
+    }
+    if (!isRecord(commandsToml.resources)) {
+        issues.push(commandContractIssue('[commands.resources] must be a TOML table'));
+        return;
+    }
+    for (const [resourceName, resource] of Object.entries(commandsToml.resources)) {
+        if (!isRecord(resource)) {
+            issues.push(commandContractIssue(`[commands.resources.${resourceName}] must be a TOML table`));
+            continue;
+        }
+        validateStringField(resource, 'type', `[commands.resources.${resourceName}].type`, issues);
+        if (hasOwn(resource, 'paths')) {
+            const paths = resource.paths;
+            if (!Array.isArray(paths) || paths.some((entry) => typeof entry !== 'string' || entry.trim().length === 0)) {
+                issues.push(commandContractIssue(`[commands.resources.${resourceName}].paths must be a string array`));
+            }
+        }
+        validateAllowedStringField(resource, 'concurrency', `[commands.resources.${resourceName}].concurrency`, new Set(['shared_reader', 'exclusive_writer', 'exclusive']), issues);
+        validateStringField(resource, 'description', `[commands.resources.${resourceName}].description`, issues);
+    }
+}
+function validateCommandIntentEffects(intentName, intent, issues) {
+    if (!hasOwn(intent, 'effects')) {
+        return;
+    }
+    if (!Array.isArray(intent.effects) || intent.effects.some((entry) => !isRecord(entry))) {
+        issues.push(commandContractIssue(`[commands.intents.${intentName}].effects must be an array of tables`));
+        return;
+    }
+    for (const effect of intent.effects) {
+        const effectTable = effect;
+        validateAllowedStringField(effectTable, 'type', `[commands.intents.${intentName}].effects.type`, COMMAND_EFFECT_TYPES, issues);
+        validateAllowedStringField(effectTable, 'mode', `[commands.intents.${intentName}].effects.mode`, COMMAND_EFFECT_MODES, issues);
+        validateAllowedStringField(effectTable, 'concurrency', `[commands.intents.${intentName}].effects.concurrency`, COMMAND_EFFECT_CONCURRENCY, issues);
+        validateStringField(effectTable, 'path', `[commands.intents.${intentName}].effects.path`, issues);
+        validateStringField(effectTable, 'lock', `[commands.intents.${intentName}].effects.lock`, issues);
+        if (hasOwn(effectTable, 'paths')) {
+            const paths = effectTable.paths;
+            if (!Array.isArray(paths) || paths.some((entry) => typeof entry !== 'string' || entry.trim().length === 0)) {
+                issues.push(commandContractIssue(`[commands.intents.${intentName}].effects.paths must be a string array`));
+            }
+        }
+    }
+}
+function validateCommandIntent(intentName, intent, issues) {
+    if (!commandIntentNameIsSafe(intentName)) {
+        issues.push(commandContractIssue(`Intent ${intentName} name must contain only letters, numbers, underscores, and hyphens`));
+    }
+    validateStringField(intent, 'status', `[commands.intents.${intentName}].status`, issues);
+    validateAllowedStringField(intent, 'lifecycle', `[commands.intents.${intentName}].lifecycle`, COMMAND_LIFECYCLES, issues);
+    validateAllowedStringField(intent, 'run_policy', `[commands.intents.${intentName}].run_policy`, COMMAND_RUN_POLICIES, issues);
+    if (intent.status !== 'configured') {
+        return;
+    }
+    const lifecycle = typeof intent.lifecycle === 'string' ? intent.lifecycle : undefined;
+    const runPolicy = typeof intent.run_policy === 'string' ? intent.run_policy : undefined;
+    if (!lifecycle) {
+        issues.push(commandContractIssue(`Configured intent ${intentName} must define lifecycle`));
+    }
+    if (!runPolicy) {
+        issues.push(commandContractIssue(`Configured intent ${intentName} must define run_policy`));
+    }
+    if (lifecycle === 'oneshot') {
+        validatePositiveIntegerField(intent, 'timeout_seconds', `[commands.intents.${intentName}].timeout_seconds`, issues);
+        if (!hasOwn(intent, 'timeout_seconds')) {
+            issues.push(commandContractIssue(`Oneshot intent ${intentName} must define timeout_seconds`));
+        }
+        if (intent.stdin !== 'closed') {
+            issues.push(commandContractIssue(`Oneshot intent ${intentName} must set stdin = "closed"`));
+        }
+    }
+    if (lifecycle && LONG_RUNNING_LIFECYCLES.has(lifecycle) && runPolicy === 'agent_allowed') {
+        issues.push(commandContractIssue(`Long-running intent ${intentName} must not use run_policy = "agent_allowed"`));
+    }
+    if (!commandIntentHasCommandSource(intent)) {
+        issues.push(commandContractIssue(`Configured intent ${intentName} must define argv or mode = "shell" with cmd`));
+    }
+    if (commandIntentHasBlockedShellBackgroundPattern(intent)) {
+        issues.push(commandContractIssue(`Shell intent ${intentName} contains a blocked long-running or background pattern`));
+    }
+    if (hasOwn(intent, 'success_exit_codes')) {
+        const value = intent.success_exit_codes;
+        if (!Array.isArray(value) || value.length === 0 || value.some((entry) => !Number.isInteger(entry))) {
+            issues.push(commandContractIssue(`[commands.intents.${intentName}].success_exit_codes must be an integer array`));
+        }
+    }
+    validateCommandIntentEffects(intentName, intent, issues);
+}
+/**
+ * mf:anchor core.command-contract-validation
+ * purpose: Validate command intent declarations that gate agent-executable repository commands.
+ * search: commands.toml, intent status, lifecycle, run policy, timeout
+ * invariant: Agent-executable commands need configured status, oneshot lifecycle, timeout, and explicit command source.
+ * risk: config, security
+ */
+export function validateCommandContractConfig(commandsToml) {
+    const issues = [];
+    if (!commandsToml) {
+        return issues;
+    }
+    validateStringField(commandsToml, 'schema_version', '[commands].schema_version', issues);
+    validateCommandDefaults(commandsToml, issues);
+    validateCommandResources(commandsToml, issues);
+    if (!isRecord(commandsToml.intents)) {
+        issues.push(commandContractIssue('Missing [intents] table in .mustflow/config/commands.toml'));
+        return issues;
+    }
+    for (const [intentName, intent] of Object.entries(commandsToml.intents)) {
+        if (!isRecord(intent)) {
+            issues.push(commandContractIssue(`Intent ${intentName} must be a TOML table`));
+            continue;
+        }
+        validateCommandIntent(intentName, intent, issues);
+    }
+    return issues;
+}
+export function validateCommandContractStrictDefaults(projectRoot, commandsToml) {
+    const issues = [];
+    if (!commandsToml || !isRecord(commandsToml.defaults)) {
+        return issues;
+    }
+    if (!hasOwn(commandsToml.defaults, 'max_output_bytes')) {
+        issues.push(commandContractIssue('[commands.defaults].max_output_bytes is required'));
+    }
+    if (!hasOwn(commandsToml.defaults, 'on_timeout')) {
+        issues.push(commandContractIssue('[commands.defaults].on_timeout is required'));
+    }
+    issues.push(...validateCommandEffects(projectRoot, commandsToml));
+    issues.push(...validateCommandEffectLockWarnings(commandsToml));
+    return issues;
+}

package/dist/core/command-cwd.js

@@ -0,0 +1,12 @@
+import path from 'node:path';
+export function resolveSafeProjectCwd(projectRoot, rawCwd) {
+    const cwd = rawCwd ?? '.';
+    const resolved = path.resolve(projectRoot, cwd);
+    const root = path.resolve(projectRoot);
+    const resolvedLower = resolved.toLowerCase();
+    const rootLower = root.toLowerCase();
+    if (resolvedLower !== rootLower && !resolvedLower.startsWith(`${rootLower}${path.sep}`)) {
+        throw new Error(`Intent cwd must stay inside the current root: ${cwd}`);
+    }
+    return resolved;
+}

package/dist/core/command-effects.js

@@ -0,0 +1,182 @@
+import path from 'node:path';
+import { isRecord, readString, readStringArray, } from './config-loading.js';
+import { resolveSafeProjectCwd } from './command-cwd.js';
+export const COMMAND_EFFECT_MODES = new Set(['read', 'write', 'append', 'replace', 'delete_recreate']);
+export const COMMAND_EFFECT_TYPES = new Set(['read', 'write']);
+export const COMMAND_EFFECT_CONCURRENCY = new Set(['shared', 'exclusive']);
+function hasOwn(table, key) {
+    return Object.prototype.hasOwnProperty.call(table, key);
+}
+function normalizeRelativePath(rawPath) {
+    return rawPath.replaceAll('\\', '/').replace(/^\.\/+/u, '').replace(/\/+$/u, '') || '.';
+}
+function pathLockKey(relativePath) {
+    return `path:${normalizeRelativePath(relativePath)}`;
+}
+function validateEffectPath(projectRoot, intent, rawPath) {
+    const cwd = resolveSafeProjectCwd(projectRoot, readString(intent, 'cwd'));
+    const resolved = path.resolve(cwd, rawPath);
+    const root = path.resolve(projectRoot);
+    const resolvedLower = resolved.toLowerCase();
+    const rootLower = root.toLowerCase();
+    if (resolvedLower !== rootLower && !resolvedLower.startsWith(`${rootLower}${path.sep}`)) {
+        throw new Error(`Command effect path must stay inside the current root: ${rawPath}`);
+    }
+    return normalizeRelativePath(path.relative(projectRoot, resolved));
+}
+function readResourcePaths(commandContract, lock) {
+    const resource = commandContract.resources[lock];
+    if (!isRecord(resource)) {
+        return [];
+    }
+    return readStringArray(resource, 'paths') ?? [];
+}
+function readEffectMode(effect) {
+    const mode = readString(effect, 'mode');
+    if (mode && COMMAND_EFFECT_MODES.has(mode)) {
+        return mode;
+    }
+    const type = readString(effect, 'type');
+    return type === 'read' ? 'read' : 'write';
+}
+function effectAccess(mode, effect) {
+    const type = readString(effect, 'type');
+    if (type && COMMAND_EFFECT_TYPES.has(type)) {
+        return type;
+    }
+    return mode === 'read' ? 'read' : 'write';
+}
+function readEffectConcurrency(effect, mode, access) {
+    const concurrency = readString(effect, 'concurrency');
+    if (concurrency && COMMAND_EFFECT_CONCURRENCY.has(concurrency)) {
+        return concurrency;
+    }
+    if (mode === 'read' && access === 'read') {
+        return 'shared';
+    }
+    return 'exclusive';
+}
+function normalizeDeclaredEffect(projectRoot, commandContract, intentName, intent, effect) {
+    const mode = readEffectMode(effect);
+    const access = effectAccess(mode, effect);
+    const concurrency = readEffectConcurrency(effect, mode, access);
+    const lock = readString(effect, 'lock');
+    const rawPaths = [
+        ...(readStringArray(effect, 'paths') ?? []),
+        ...(readString(effect, 'path') ? [readString(effect, 'path')] : []),
+    ];
+    const fallbackPaths = lock ? readResourcePaths(commandContract, lock) : [];
+    const paths = rawPaths.length > 0 ? rawPaths : fallbackPaths;
+    if (!lock && paths.length === 0) {
+        throw new Error(`Command effect for intent ${intentName} must define path, paths, or lock`);
+    }
+    return paths.map((rawPath) => {
+        const normalizedPath = validateEffectPath(projectRoot, intent, rawPath);
+        return {
+            intent: intentName,
+            source: 'effects',
+            access,
+            mode,
+            path: normalizedPath,
+            lock: lock ?? pathLockKey(normalizedPath),
+            concurrency,
+        };
+    });
+}
+function normalizeWritesEffect(projectRoot, intentName, intent) {
+    const writes = readStringArray(intent, 'writes') ?? [];
+    return writes.map((rawPath) => {
+        const normalizedPath = validateEffectPath(projectRoot, intent, rawPath);
+        return {
+            intent: intentName,
+            source: 'writes',
+            access: 'write',
+            mode: 'write',
+            path: normalizedPath,
+            lock: pathLockKey(normalizedPath),
+            concurrency: 'exclusive',
+        };
+    });
+}
+export function normalizeCommandEffects(projectRoot, commandContract, intentName) {
+    const intent = commandContract.intents[intentName];
+    if (!isRecord(intent)) {
+        return [];
+    }
+    const rawEffects = intent.effects;
+    if (Array.isArray(rawEffects) && rawEffects.length > 0) {
+        return rawEffects.flatMap((effect) => isRecord(effect) ? normalizeDeclaredEffect(projectRoot, commandContract, intentName, intent, effect) : []);
+    }
+    return normalizeWritesEffect(projectRoot, intentName, intent);
+}
+export function commandEffectsConflict(left, right) {
+    if (left.lock !== right.lock) {
+        return false;
+    }
+    if (left.mode === 'delete_recreate' || right.mode === 'delete_recreate') {
+        return true;
+    }
+    if (left.concurrency === 'exclusive' || right.concurrency === 'exclusive') {
+        return true;
+    }
+    return left.access === 'write' || right.access === 'write';
+}
+export function validateCommandEffects(projectRoot, commandsToml) {
+    const issues = [];
+    if (!commandsToml || !isRecord(commandsToml.intents)) {
+        return issues;
+    }
+    const commandContract = {
+        defaults: isRecord(commandsToml.defaults) ? commandsToml.defaults : {},
+        intents: commandsToml.intents,
+        resources: isRecord(commandsToml.resources) ? commandsToml.resources : {},
+    };
+    for (const [intentName, intent] of Object.entries(commandContract.intents)) {
+        if (!isRecord(intent)) {
+            continue;
+        }
+        if (hasOwn(intent, 'effects') && (!Array.isArray(intent.effects) || intent.effects.some((effect) => !isRecord(effect)))) {
+            issues.push({ message: `[commands.intents.${intentName}].effects must be an array of tables` });
+            continue;
+        }
+        try {
+            normalizeCommandEffects(projectRoot, commandContract, intentName);
+        }
+        catch (error) {
+            issues.push({ message: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return issues;
+}
+export function validateCommandEffectLockWarnings(commandsToml) {
+    const issues = [];
+    if (!commandsToml || !isRecord(commandsToml.intents)) {
+        return issues;
+    }
+    const lockToIntents = new Map();
+    for (const [intentName, intent] of Object.entries(commandsToml.intents)) {
+        if (!isRecord(intent)) {
+            continue;
+        }
+        if (intent.status !== 'configured' ||
+            intent.lifecycle !== 'oneshot' ||
+            intent.run_policy !== 'agent_allowed' ||
+            Array.isArray(intent.effects)) {
+            continue;
+        }
+        for (const rawPath of readStringArray(intent, 'writes') ?? []) {
+            const lock = pathLockKey(rawPath);
+            lockToIntents.set(lock, [...(lockToIntents.get(lock) ?? []), intentName]);
+        }
+    }
+    for (const [lock, intents] of lockToIntents) {
+        if (intents.length < 2) {
+            continue;
+        }
+        issues.push({
+            severity: 'warning',
+            message: `configured agent-runnable intents ${intents.sort((left, right) => left.localeCompare(right)).join(', ')} share ${lock} through writes without explicit effects or resource locks`,
+        });
+    }
+    return issues;
+}

package/dist/core/command-explanation.js

@@ -0,0 +1,135 @@
+import { isRecord, readPositiveInteger, readString, readStringArray, } from './config-loading.js';
+const COMMAND_CONTRACT_SOURCE_FILES = [
+    'AGENTS.md',
+    '.mustflow/docs/agent-workflow.md',
+    '.mustflow/config/commands.toml',
+    '.mustflow/config/mustflow.toml',
+];
+const ASSET_OPTIMIZATION_SOURCE_FILES = [
+    '.mustflow/skills/INDEX.md',
+    '.mustflow/skills/web-asset-optimization/SKILL.md',
+    '.mustflow/config/commands.toml',
+    '.mustflow/config/mustflow.toml',
+];
+function readOptionalStringArray(table, key) {
+    return readStringArray(table, key) ?? [];
+}
+function readOptionalBoolean(table, key) {
+    const value = table[key];
+    return typeof value === 'boolean' ? value : null;
+}
+function readOptionalIntegerArray(table, key) {
+    const value = table[key];
+    if (!Array.isArray(value) || value.some((entry) => !Number.isInteger(entry))) {
+        return [];
+    }
+    return value.map((entry) => Number(entry));
+}
+function resolveCommandMode(intent) {
+    const argv = readStringArray(intent, 'argv');
+    const shellCommand = intent.mode === 'shell' ? readString(intent, 'cmd') : undefined;
+    if (argv && argv.length > 0) {
+        return 'argv';
+    }
+    if (shellCommand) {
+        return 'shell';
+    }
+    return 'missing';
+}
+function summarizeIntent(name, intent) {
+    return {
+        name,
+        status: readString(intent, 'status') ?? null,
+        lifecycle: readString(intent, 'lifecycle') ?? null,
+        runPolicy: readString(intent, 'run_policy') ?? null,
+        stdin: readString(intent, 'stdin') ?? null,
+        timeoutSeconds: readPositiveInteger(intent, 'timeout_seconds') ?? null,
+        mode: resolveCommandMode(intent),
+        cwd: readString(intent, 'cwd') ?? null,
+        writes: readOptionalStringArray(intent, 'writes'),
+        network: readOptionalBoolean(intent, 'network'),
+        destructive: readOptionalBoolean(intent, 'destructive'),
+        successExitCodes: readOptionalIntegerArray(intent, 'success_exit_codes'),
+        requiredAfter: readOptionalStringArray(intent, 'required_after'),
+    };
+}
+function collectBlockingReasons(summary) {
+    const reasons = [];
+    if (summary.status !== 'configured') {
+        reasons.push(`status is ${summary.status ?? 'missing'}, not configured`);
+    }
+    if (summary.lifecycle !== 'oneshot') {
+        reasons.push(`lifecycle is ${summary.lifecycle ?? 'missing'}, not oneshot`);
+    }
+    if (summary.runPolicy !== 'agent_allowed') {
+        reasons.push(`run_policy is ${summary.runPolicy ?? 'missing'}, not agent_allowed`);
+    }
+    if (summary.stdin !== 'closed') {
+        reasons.push(`stdin is ${summary.stdin ?? 'missing'}, not closed`);
+    }
+    if (summary.timeoutSeconds === null) {
+        reasons.push('timeout_seconds is missing or invalid');
+    }
+    if (summary.mode === 'missing') {
+        reasons.push('no argv command or shell cmd is declared');
+    }
+    return reasons;
+}
+export function explainCommandIntent(contract, commandName) {
+    const intentCandidate = contract.intents[commandName];
+    if (!isRecord(intentCandidate)) {
+        return {
+            kind: 'unknown',
+            inputCommand: commandName,
+            decision: `command intent "${commandName}" is not declared`,
+            reason: 'mustflow does not infer commands from package manager files or repository conventions.',
+            effectiveAction: 'Do not run a guessed command; add a configured intent or report the missing command contract.',
+            countsAsMustflowVerification: false,
+            sourceFiles: COMMAND_CONTRACT_SOURCE_FILES,
+            intent: null,
+        };
+    }
+    const intent = summarizeIntent(commandName, intentCandidate);
+    const blockingReasons = collectBlockingReasons(intent);
+    if (blockingReasons.length === 0) {
+        return {
+            kind: 'allowed',
+            inputCommand: commandName,
+            decision: `command intent "${commandName}" is allowed through mf run`,
+            reason: 'the intent is configured, one-shot, agent-allowed, closed-stdin, bounded by a timeout, and has an explicit command source.',
+            effectiveAction: `Run mf run ${commandName} when this intent is required for the changed behavior.`,
+            countsAsMustflowVerification: true,
+            sourceFiles: COMMAND_CONTRACT_SOURCE_FILES,
+            intent,
+        };
+    }
+    return {
+        kind: 'blocked',
+        inputCommand: commandName,
+        decision: `command intent "${commandName}" is not agent-runnable`,
+        reason: blockingReasons.join('; '),
+        effectiveAction: 'Do not run this command as verification; report the command-contract reason instead.',
+        countsAsMustflowVerification: false,
+        sourceFiles: COMMAND_CONTRACT_SOURCE_FILES,
+        intent,
+    };
+}
+export function explainAssetOptimization(contract) {
+    const decision = explainCommandIntent(contract, 'asset_optimize');
+    if (decision.kind === 'allowed') {
+        return {
+            ...decision,
+            decision: 'web asset optimization has a configured command intent',
+            reason: 'the web-asset-optimization skill is available and asset_optimize is configured as an agent-runnable command intent.',
+            effectiveAction: 'Read .mustflow/skills/web-asset-optimization/SKILL.md, then run mf run asset_optimize when image asset changes require optimization evidence.',
+            sourceFiles: ASSET_OPTIMIZATION_SOURCE_FILES,
+        };
+    }
+    return {
+        ...decision,
+        decision: 'web asset optimization is skill-guided but command-gated',
+        reason: 'the web-asset-optimization skill applies to web image asset work, but asset_optimize is not currently an agent-runnable configured intent.',
+        effectiveAction: 'Read .mustflow/skills/web-asset-optimization/SKILL.md, do not guess external converters or package commands, and report the missing asset_optimize contract when optimization evidence is required.',
+        sourceFiles: ASSET_OPTIMIZATION_SOURCE_FILES,
+    };
+}

package/dist/core/command-intent-eligibility.js

@@ -0,0 +1,76 @@
+import { isRecord, readString } from './config-loading.js';
+import { commandIntentHasBlockedShellBackgroundPattern, commandIntentHasCommandSource, commandIntentNameIsSafe, } from './command-contract-rules.js';
+export function evaluateCommandIntentEligibility(intentName, rawIntent) {
+    if (!commandIntentNameIsSafe(intentName)) {
+        return {
+            ok: false,
+            code: 'unsafe_intent_name',
+            detail: 'Intent name can contain only ASCII letters, numbers, underscores, and hyphens.',
+        };
+    }
+    if (!isRecord(rawIntent)) {
+        return {
+            ok: false,
+            code: 'intent_not_table',
+            detail: 'Intent is not a TOML table.',
+        };
+    }
+    const status = readString(rawIntent, 'status') ?? 'unknown';
+    if (status !== 'configured') {
+        const reason = readString(rawIntent, 'reason');
+        return {
+            ok: false,
+            code: 'status_not_configured',
+            detail: reason ?? `Intent status is ${status}.`,
+        };
+    }
+    const lifecycle = readString(rawIntent, 'lifecycle');
+    if (lifecycle !== 'oneshot') {
+        return {
+            ok: false,
+            code: 'lifecycle_not_oneshot',
+            detail: `Intent lifecycle is ${lifecycle ?? 'unknown'}.`,
+        };
+    }
+    const runPolicy = readString(rawIntent, 'run_policy');
+    if (runPolicy !== 'agent_allowed') {
+        return {
+            ok: false,
+            code: 'run_policy_not_agent_allowed',
+            detail: `Intent run_policy is ${runPolicy ?? 'unknown'}.`,
+        };
+    }
+    if (rawIntent.stdin !== 'closed') {
+        return {
+            ok: false,
+            code: 'stdin_not_closed',
+            detail: 'Intent stdin is not closed.',
+        };
+    }
+    if (!Number.isInteger(rawIntent.timeout_seconds) || Number(rawIntent.timeout_seconds) <= 0) {
+        return {
+            ok: false,
+            code: 'missing_timeout',
+            detail: 'Intent timeout_seconds is missing or invalid.',
+        };
+    }
+    if (!commandIntentHasCommandSource(rawIntent)) {
+        return {
+            ok: false,
+            code: 'missing_command_source',
+            detail: 'Intent does not define argv or shell cmd.',
+        };
+    }
+    if (commandIntentHasBlockedShellBackgroundPattern(rawIntent)) {
+        return {
+            ok: false,
+            code: 'blocked_shell_background_pattern',
+            detail: 'Shell command contains a blocked long-running or background pattern.',
+        };
+    }
+    return {
+        ok: true,
+        code: 'ok',
+        detail: null,
+    };
+}

package/dist/core/config-loading.js

@@ -0,0 +1,54 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { readTomlFile } from './toml.js';
+export const COMMAND_LIFECYCLES = new Set(['oneshot', 'server', 'watch', 'interactive', 'browser', 'background']);
+export const LONG_RUNNING_LIFECYCLES = new Set(['server', 'watch', 'interactive', 'browser', 'background']);
+export const COMMAND_RUN_POLICIES = new Set(['agent_allowed', 'requires_explicit_user_request', 'manual_only']);
+export const COMMANDS_CONFIG_RELATIVE_PATH = '.mustflow/config/commands.toml';
+export const MUSTFLOW_CONFIG_RELATIVE_PATH = '.mustflow/config/mustflow.toml';
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function resolveMustflowConfigPath(projectRoot, relativePath) {
+    return path.join(projectRoot, ...relativePath.split('/'));
+}
+export function readMustflowConfig(projectRoot) {
+    const parsed = readTomlFile(resolveMustflowConfigPath(projectRoot, MUSTFLOW_CONFIG_RELATIVE_PATH));
+    if (!isRecord(parsed)) {
+        throw new Error(`${MUSTFLOW_CONFIG_RELATIVE_PATH} must contain a TOML table`);
+    }
+    return parsed;
+}
+export function readMustflowConfigIfExists(projectRoot) {
+    const configPath = resolveMustflowConfigPath(projectRoot, MUSTFLOW_CONFIG_RELATIVE_PATH);
+    return existsSync(configPath) ? readMustflowConfig(projectRoot) : undefined;
+}
+export function readCommandContract(projectRoot) {
+    const parsed = readTomlFile(resolveMustflowConfigPath(projectRoot, COMMANDS_CONFIG_RELATIVE_PATH));
+    if (!isRecord(parsed)) {
+        throw new Error(`${COMMANDS_CONFIG_RELATIVE_PATH} must contain a TOML table`);
+    }
+    if (!isRecord(parsed.intents)) {
+        throw new Error(`Missing [intents] table in ${COMMANDS_CONFIG_RELATIVE_PATH}`);
+    }
+    return {
+        defaults: isRecord(parsed.defaults) ? parsed.defaults : {},
+        intents: parsed.intents,
+        resources: isRecord(parsed.resources) ? parsed.resources : {},
+    };
+}
+export function readString(table, key) {
+    const value = table[key];
+    return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+}
+export function readPositiveInteger(table, key) {
+    const value = table[key];
+    return Number.isInteger(value) && Number(value) > 0 ? Number(value) : undefined;
+}
+export function readStringArray(table, key) {
+    const value = table[key];
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+        return undefined;
+    }
+    return [...value];
+}