mustflow 2.112.14 → 2.114.0

package/dist/cli/lib/external-skill-import.js

@@ -1,13 +1,19 @@
-import { existsSync, renameSync, rmSync } from 'node:fs';
+import { existsSync, readdirSync, renameSync, rmSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import path from 'node:path';
-import { ensureFileTargetInsideWithoutSymlinks, writeJsonFileInsideWithoutSymlinks, writeUtf8FileInsideWithoutSymlinks, } from '../../core/safe-filesystem.js';
+import { readCommandContract, readCommandContractIncludePaths, } from '../../core/config-loading.js';
+import { ensureFileTargetInsideWithoutSymlinks, readUtf8FileInsideWithoutSymlinks, writeJsonFileInsideWithoutSymlinks, writeUtf8FileInsideWithoutSymlinks, } from '../../core/safe-filesystem.js';
 const EXTERNAL_SKILL_ROOT = '.mustflow/external-skills';
 const PROVENANCE_FILE = 'mustflow-skill-source.json';
+const COMMANDS_CONFIG_PATH = '.mustflow/config/commands.toml';
+const COMMAND_FRAGMENT_DIRECTORY = '.mustflow/config/commands';
+const EXTERNAL_SKILL_UPDATE_CHECK_STATE_PATH = '.mustflow/state/external-skills/update-check.json';
 const DEFAULT_GITHUB_REF = 'HEAD';
 const MAX_IMPORTED_FILES = 40;
 const MAX_TOTAL_BYTES = 512 * 1024;
 const MAX_FILE_BYTES = 256 * 1024;
+const UPDATE_CHECK_STALE_AFTER_DAYS = 7;
+const UPDATE_CHECK_STALE_AFTER_MS = UPDATE_CHECK_STALE_AFTER_DAYS * 24 * 60 * 60 * 1000;
 const ALLOWED_SUPPORT_DIRECTORIES = new Set(['assets', 'references', 'scripts']);
 const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
 const GITHUB_NAME_PATTERN = /^[A-Za-z0-9_.-]+$/u;
@@ -130,6 +136,9 @@ function sanitizeSkillName(value) {
         .replace(/^-+|-+$/gu, '')
         .replace(/-{2,}/gu, '-');
 }
+function commandSafeSegment(value) {
+    return sanitizeSkillName(value).replace(/-/gu, '_');
+}
 function readFrontmatterScalar(content, key) {
     if (!content.startsWith('---')) {
         return null;
@@ -359,7 +368,391 @@ function createTarget(skillName) {
         provenance_path: `${skillDir}/${PROVENANCE_FILE}`,
     };
 }
-function writeImportedSkillFiles(projectRoot, target, source, files, fileReport, warnings) {
+function sourceToParsed(source) {
+    return {
+        host: source.host,
+        owner: source.owner,
+        repo: source.repo,
+        ref: source.ref,
+        skillPath: source.skill_path,
+        sourceUrl: source.source_url,
+    };
+}
+function provenancePathForSkill(skillName) {
+    return `${EXTERNAL_SKILL_ROOT}/${skillName}/${PROVENANCE_FILE}`;
+}
+function readJsonFile(projectRoot, relativePath, maxBytes = 512 * 1024) {
+    const content = readUtf8FileInsideWithoutSymlinks(projectRoot, path.join(projectRoot, ...relativePath.split('/')), { maxBytes });
+    return JSON.parse(content);
+}
+function assertExternalSkillSource(value, skillName) {
+    if (!value || typeof value !== 'object') {
+        throw new Error(`External skill provenance is not an object: ${skillName}`);
+    }
+    const record = value;
+    if (record.schema_version !== '1' || record.kind !== 'external_skill_source') {
+        throw new Error(`External skill provenance has an unsupported shape: ${skillName}`);
+    }
+    if (!record.source || typeof record.source !== 'object') {
+        throw new Error(`External skill provenance is missing source metadata: ${skillName}`);
+    }
+    if (!Array.isArray(record.files)) {
+        throw new Error(`External skill provenance is missing file hashes: ${skillName}`);
+    }
+    return record;
+}
+function installedExternalSkillNames(projectRoot) {
+    const rootPath = path.join(projectRoot, ...EXTERNAL_SKILL_ROOT.split('/'));
+    if (!existsSync(rootPath)) {
+        return [];
+    }
+    return readdirSync(rootPath, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .filter((name) => SLUG_PATTERN.test(name) && existsSync(path.join(rootPath, name, PROVENANCE_FILE)))
+        .sort((left, right) => left.localeCompare(right));
+}
+function readExternalSkillProvenance(projectRoot, skillName) {
+    return assertExternalSkillSource(readJsonFile(projectRoot, provenancePathForSkill(skillName)), skillName);
+}
+function readExternalSkillUpdateCheckStateFile(projectRoot) {
+    const statePath = path.join(projectRoot, ...EXTERNAL_SKILL_UPDATE_CHECK_STATE_PATH.split('/'));
+    if (!existsSync(statePath)) {
+        return null;
+    }
+    try {
+        const value = readJsonFile(projectRoot, EXTERNAL_SKILL_UPDATE_CHECK_STATE_PATH, 64 * 1024);
+        if (!value || typeof value !== 'object') {
+            return null;
+        }
+        const record = value;
+        if (record.schema_version !== '1' ||
+            record.kind !== 'external_skill_update_check_state' ||
+            typeof record.last_checked_at !== 'string' ||
+            Number.isNaN(Date.parse(record.last_checked_at))) {
+            return null;
+        }
+        return {
+            schema_version: '1',
+            kind: 'external_skill_update_check_state',
+            last_checked_at: record.last_checked_at,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function createExternalSkillUpdateCheckState(projectRoot, now) {
+    const previous = readExternalSkillUpdateCheckStateFile(projectRoot);
+    const checkedAt = now.toISOString();
+    const nextCheckDueAt = new Date(now.getTime() + UPDATE_CHECK_STALE_AFTER_MS).toISOString();
+    const previousTime = previous ? Date.parse(previous.last_checked_at) : Number.NaN;
+    const hasInstalledExternalSkills = installedExternalSkillNames(projectRoot).length > 0;
+    const staleBeforeCommand = hasInstalledExternalSkills && (!previous ||
+        Number.isNaN(previousTime) ||
+        now.getTime() - previousTime >= UPDATE_CHECK_STALE_AFTER_MS);
+    return {
+        state_path: EXTERNAL_SKILL_UPDATE_CHECK_STATE_PATH,
+        stale_after_days: UPDATE_CHECK_STALE_AFTER_DAYS,
+        checked_at: checkedAt,
+        previous_checked_at: previous?.last_checked_at ?? null,
+        next_check_due_at: nextCheckDueAt,
+        stale_before_command: staleBeforeCommand,
+    };
+}
+function writeExternalSkillUpdateCheckState(projectRoot, checkedAt) {
+    writeJsonFileInsideWithoutSymlinks(projectRoot, path.join(projectRoot, ...EXTERNAL_SKILL_UPDATE_CHECK_STATE_PATH.split('/')), {
+        schema_version: '1',
+        kind: 'external_skill_update_check_state',
+        last_checked_at: checkedAt,
+    });
+}
+export function createExternalSkillUpdateReminder(projectRoot, now = new Date()) {
+    const hasInstalledExternalSkills = installedExternalSkillNames(projectRoot).length > 0;
+    if (!hasInstalledExternalSkills) {
+        return null;
+    }
+    const previous = readExternalSkillUpdateCheckStateFile(projectRoot);
+    const previousTime = previous ? Date.parse(previous.last_checked_at) : Number.NaN;
+    if (previous && !Number.isNaN(previousTime) && now.getTime() - previousTime < UPDATE_CHECK_STALE_AFTER_MS) {
+        return null;
+    }
+    return `External skill update check is stale; run mf skill outdated --json or mf skill update --all --dry-run --json. Last checked: ${previous?.last_checked_at ?? 'never'}.`;
+}
+function readInstalledRelativeFilePaths(projectRoot, target) {
+    const targetPath = path.join(projectRoot, ...target.skill_dir.split('/'));
+    const pending = [''];
+    const files = [];
+    const stack = [...pending];
+    while (stack.length > 0) {
+        const relativeDirectory = stack.pop() ?? '';
+        const absoluteDirectory = relativeDirectory
+            ? path.join(targetPath, ...relativeDirectory.split('/'))
+            : targetPath;
+        const entries = readdirSync(absoluteDirectory, { withFileTypes: true })
+            .sort((left, right) => left.name.localeCompare(right.name));
+        for (const entry of entries) {
+            const relativePath = relativeDirectory ? `${relativeDirectory}/${entry.name}` : entry.name;
+            if (relativePath === PROVENANCE_FILE) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                stack.push(relativePath);
+                continue;
+            }
+            files.push(relativePath);
+            if (files.length > MAX_IMPORTED_FILES) {
+                throw new Error(`External skill ${target.skill_name} exceeds ${MAX_IMPORTED_FILES} installed files.`);
+            }
+        }
+    }
+    return files.sort((left, right) => left.localeCompare(right));
+}
+function readInstalledFileReports(projectRoot, target, provenanceFiles) {
+    return provenanceFiles.map((file) => {
+        const relativePath = `${target.skill_dir}/${file.relative_path}`;
+        const content = readUtf8FileInsideWithoutSymlinks(projectRoot, path.join(projectRoot, ...relativePath.split('/')), { maxBytes: MAX_FILE_BYTES });
+        return {
+            relative_path: file.relative_path,
+            kind: file.kind,
+            bytes: Buffer.byteLength(content, 'utf8'),
+            sha256: hashContent(content),
+        };
+    });
+}
+function collectFileChanges(currentFiles, remoteFiles) {
+    const currentByPath = new Map(currentFiles.map((file) => [file.relative_path, file]));
+    const remoteByPath = new Map(remoteFiles.map((file) => [file.relative_path, file]));
+    const paths = [...new Set([...currentByPath.keys(), ...remoteByPath.keys()])].sort((left, right) => left.localeCompare(right));
+    const changes = [];
+    for (const relativePath of paths) {
+        const current = currentByPath.get(relativePath);
+        const remote = remoteByPath.get(relativePath);
+        if (!current && remote) {
+            changes.push({
+                relative_path: relativePath,
+                status: 'added',
+                current_sha256: null,
+                remote_sha256: remote.sha256,
+            });
+            continue;
+        }
+        if (current && !remote) {
+            changes.push({
+                relative_path: relativePath,
+                status: 'removed',
+                current_sha256: current.sha256,
+                remote_sha256: null,
+            });
+            continue;
+        }
+        if (current && remote && current.sha256 !== remote.sha256) {
+            changes.push({
+                relative_path: relativePath,
+                status: 'modified',
+                current_sha256: current.sha256,
+                remote_sha256: remote.sha256,
+            });
+        }
+    }
+    return changes;
+}
+function localDriftIssues(skillName, provenanceFiles, installedFiles, installedRelativeFilePaths) {
+    const provenanceByPath = new Map(provenanceFiles.map((file) => [file.relative_path, file]));
+    const provenancePaths = new Set(provenanceFiles.map((file) => file.relative_path));
+    const issues = [];
+    for (const installed of installedFiles) {
+        const provenance = provenanceByPath.get(installed.relative_path);
+        if (!provenance || provenance.sha256 !== installed.sha256) {
+            issues.push(`External skill ${skillName} has local file drift: ${installed.relative_path}`);
+        }
+    }
+    for (const relativePath of installedRelativeFilePaths) {
+        if (!provenancePaths.has(relativePath)) {
+            issues.push(`External skill ${skillName} has local file drift: ${relativePath}`);
+        }
+    }
+    return issues;
+}
+function scriptNameForIntent(relativePath) {
+    const basename = path.posix.basename(relativePath);
+    const withoutExtension = basename.replace(/\.[^.]+$/u, '');
+    const sanitized = commandSafeSegment(withoutExtension);
+    if (!sanitized) {
+        throw new Error(`External script path cannot be converted to a safe intent name: ${relativePath}`);
+    }
+    return sanitized;
+}
+function trustedScriptArgv(skillName, scriptPath) {
+    const extension = path.posix.extname(scriptPath).toLowerCase();
+    const projectScriptPath = `${EXTERNAL_SKILL_ROOT}/${skillName}/${scriptPath}`;
+    if (['.js', '.mjs', '.cjs'].includes(extension)) {
+        return ['node', projectScriptPath];
+    }
+    if (['.ts', '.mts', '.cts'].includes(extension)) {
+        return ['bun', projectScriptPath];
+    }
+    if (extension === '.ps1') {
+        return ['pwsh', '-NoProfile', '-File', projectScriptPath];
+    }
+    if (extension === '.sh') {
+        return ['sh', projectScriptPath];
+    }
+    throw new Error(`External script import cannot create a trusted command intent for unsupported script type: ${scriptPath}`);
+}
+function createTrustedScriptIntent(skillName, scriptPath) {
+    return {
+        intent: `external_skill_${commandSafeSegment(skillName)}_${scriptNameForIntent(scriptPath)}`,
+        script_path: scriptPath,
+        argv: trustedScriptArgv(skillName, scriptPath),
+        run_policy: 'agent_allowed',
+        network: true,
+        destructive: true,
+        approval_required: ['network_access', 'destructive_command'],
+    };
+}
+function createScriptTrust(projectRoot, target, files, trustScripts, mode, existingTrust) {
+    const scripts = files.filter((file) => file.kind === 'script');
+    if (!trustScripts) {
+        return {
+            requested: false,
+            status: 'not_requested',
+            grants_command_authority: false,
+            command_contract_path: null,
+            include_entry: null,
+            fragment_path: null,
+            intents: [],
+        };
+    }
+    if (scripts.length === 0) {
+        return {
+            requested: true,
+            status: 'no_scripts',
+            grants_command_authority: false,
+            command_contract_path: null,
+            include_entry: null,
+            fragment_path: null,
+            intents: [],
+        };
+    }
+    const fragmentName = `external-skills-${target.skill_name}.toml`;
+    const includeEntry = `commands/${fragmentName}`;
+    const fragmentPath = `${COMMAND_FRAGMENT_DIRECTORY}/${fragmentName}`;
+    const intents = scripts.map((script) => createTrustedScriptIntent(target.skill_name, script.relative_path));
+    const duplicateIntent = findDuplicate(intents.map((intent) => intent.intent));
+    if (duplicateIntent) {
+        throw new Error(`External skill trusted script intents contain a duplicate name: ${duplicateIntent}`);
+    }
+    validateTrustedScriptCommandPlan(projectRoot, includeEntry, fragmentPath, intents, existingTrust);
+    return {
+        requested: true,
+        status: mode === 'install' ? 'trusted' : 'planned',
+        grants_command_authority: mode === 'install',
+        command_contract_path: COMMANDS_CONFIG_PATH,
+        include_entry: includeEntry,
+        fragment_path: fragmentPath,
+        intents,
+    };
+}
+function findDuplicate(values) {
+    const seen = new Set();
+    for (const value of values) {
+        if (seen.has(value)) {
+            return value;
+        }
+        seen.add(value);
+    }
+    return null;
+}
+function validateTrustedScriptCommandPlan(projectRoot, includeEntry, fragmentPath, intents, existingTrust) {
+    const existingIncludes = new Set(readCommandContractIncludePaths(projectRoot).map((entry) => entry.replace(/^\.mustflow\/config\//u, '')));
+    const fragmentExists = existsSync(path.join(projectRoot, ...fragmentPath.split('/')));
+    const mayReuseExistingPlan = existingTrust?.grants_command_authority === true &&
+        existingTrust.include_entry === includeEntry &&
+        existingTrust.fragment_path === fragmentPath &&
+        existingIncludes.has(includeEntry) &&
+        fragmentExists;
+    const reusableIntentNames = new Set(mayReuseExistingPlan ? existingTrust.intents.map((intent) => intent.intent) : []);
+    if (existingIncludes.has(includeEntry) && !mayReuseExistingPlan) {
+        throw new Error(`External skill trusted script command include already exists: ${includeEntry}`);
+    }
+    if (fragmentExists && !mayReuseExistingPlan) {
+        throw new Error(`External skill trusted script command fragment already exists: ${fragmentPath}`);
+    }
+    const contract = readCommandContract(projectRoot);
+    for (const intent of intents) {
+        if (Object.prototype.hasOwnProperty.call(contract.intents, intent.intent) && !reusableIntentNames.has(intent.intent)) {
+            throw new Error(`External skill trusted script intent already exists in command contract: ${intent.intent}`);
+        }
+    }
+}
+function renderTomlString(value) {
+    return JSON.stringify(value);
+}
+function renderTomlStringArray(values) {
+    return `[${values.map(renderTomlString).join(', ')}]`;
+}
+function renderTrustedScriptCommandFragment(target, source, scriptTrust) {
+    const lines = [
+        `# Generated by mf skill import --trust-scripts for external skill ${JSON.stringify(target.skill_name)}.`,
+        `# Source: ${source.source_url}`,
+        '# These intents execute imported external script files. They are agent-runnable only through mf run,',
+        '# and remain gated by network_access and destructive_command approvals.',
+        '',
+    ];
+    for (const intent of scriptTrust.intents) {
+        lines.push(`[intents.${intent.intent}]`, 'status = "configured"', 'lifecycle = "oneshot"', 'run_policy = "agent_allowed"', `description = ${renderTomlString(`Run trusted external skill script ${intent.script_path} from ${target.skill_name}.`)}`, `argv = ${renderTomlStringArray(intent.argv)}`, 'cwd = "."', 'timeout_seconds = 300', 'stdin = "closed"', 'success_exit_codes = [0]', 'writes = []', 'network = true', 'destructive = true', 'env_policy = "minimal"', '');
+    }
+    return lines.join('\n');
+}
+function updateCommandIncludeText(content, includeEntry) {
+    const normalizedContent = content.replace(/\r\n?/gu, '\n');
+    const lines = normalizedContent.split('\n');
+    const includeLineIndex = lines.findIndex((line) => /^\s*\[include\]\s*$/u.test(line));
+    const includeLine = `  ${renderTomlString(includeEntry)},`;
+    if (includeLineIndex < 0) {
+        const separator = normalizedContent.endsWith('\n') ? '' : '\n';
+        return `${normalizedContent}${separator}\n[include]\nfiles = [\n${includeLine}\n]\n`;
+    }
+    const nextSectionIndex = lines.findIndex((line, index) => index > includeLineIndex && /^\s*\[[^\]]+\]\s*$/u.test(line));
+    const sectionEnd = nextSectionIndex < 0 ? lines.length : nextSectionIndex;
+    const filesLineIndex = lines.findIndex((line, index) => index > includeLineIndex &&
+        index < sectionEnd &&
+        /^\s*files\s*=\s*\[/u.test(line));
+    if (filesLineIndex < 0) {
+        lines.splice(includeLineIndex + 1, 0, 'files = [', includeLine, ']');
+        return lines.join('\n');
+    }
+    if (lines[filesLineIndex].includes(']')) {
+        const existingValues = [...lines[filesLineIndex].matchAll(/"([^"]+)"/gu)].map((match) => match[1]);
+        const values = [...new Set([...existingValues, includeEntry])].sort((left, right) => left.localeCompare(right));
+        lines.splice(filesLineIndex, 1, 'files = [', ...values.map((entry) => `  ${renderTomlString(entry)},`), ']');
+        return lines.join('\n');
+    }
+    const closingLineIndex = lines.findIndex((line, index) => index > filesLineIndex && index < sectionEnd && /^\s*\]\s*$/u.test(line));
+    if (closingLineIndex < 0) {
+        throw new Error(`[include].files in ${COMMANDS_CONFIG_PATH} must be a TOML array`);
+    }
+    const existingValues = lines
+        .slice(filesLineIndex + 1, closingLineIndex)
+        .flatMap((line) => [...line.matchAll(/"([^"]+)"/gu)].map((match) => match[1]));
+    if (existingValues.includes(includeEntry)) {
+        return lines.join('\n');
+    }
+    lines.splice(closingLineIndex, 0, includeLine);
+    return lines.join('\n');
+}
+function writeTrustedScriptCommandContract(projectRoot, target, source, scriptTrust) {
+    if (scriptTrust.status !== 'trusted' || !scriptTrust.fragment_path || !scriptTrust.include_entry) {
+        return;
+    }
+    const fragmentContent = renderTrustedScriptCommandFragment(target, source, scriptTrust);
+    writeUtf8FileInsideWithoutSymlinks(projectRoot, path.join(projectRoot, ...scriptTrust.fragment_path.split('/')), fragmentContent);
+    const commandsPath = path.join(projectRoot, ...COMMANDS_CONFIG_PATH.split('/'));
+    const commandsContent = readUtf8FileInsideWithoutSymlinks(projectRoot, commandsPath, { maxBytes: 256 * 1024 });
+    writeUtf8FileInsideWithoutSymlinks(projectRoot, commandsPath, updateCommandIncludeText(commandsContent, scriptTrust.include_entry));
+}
+function writeImportedSkillFiles(projectRoot, target, source, files, fileReport, warnings, scriptTrust) {
     const targetPath = path.join(projectRoot, ...target.skill_dir.split('/'));
     const skillPath = path.join(targetPath, 'SKILL.md');
     if (existsSync(targetPath)) {
@@ -384,6 +777,7 @@ function writeImportedSkillFiles(projectRoot, target, source, files, fileReport,
             kind: 'external_skill_source',
             source,
             files: fileReport,
+            script_trust: scriptTrust,
             warnings,
         });
         renameSync(tempPath, targetPath);
@@ -393,6 +787,45 @@ function writeImportedSkillFiles(projectRoot, target, source, files, fileReport,
         throw error;
     }
 }
+function writeUpdatedSkillFiles(projectRoot, target, source, files, fileReport, warnings, scriptTrust) {
+    const targetPath = path.join(projectRoot, ...target.skill_dir.split('/'));
+    if (!existsSync(targetPath)) {
+        throw new Error(`External skill is not installed: ${target.skill_dir}`);
+    }
+    const timestamp = Date.now();
+    const tempSkillDir = `${EXTERNAL_SKILL_ROOT}/.${target.skill_name}.update-${process.pid}-${timestamp}`;
+    const backupSkillDir = `${EXTERNAL_SKILL_ROOT}/.${target.skill_name}.backup-${process.pid}-${timestamp}`;
+    const tempPath = path.join(projectRoot, ...tempSkillDir.split('/'));
+    const backupPath = path.join(projectRoot, ...backupSkillDir.split('/'));
+    const tempSkillPath = path.join(tempPath, 'SKILL.md');
+    ensureFileTargetInsideWithoutSymlinks(projectRoot, tempSkillPath, { allowMissingLeaf: true });
+    try {
+        for (const file of files) {
+            writeUtf8FileInsideWithoutSymlinks(projectRoot, path.join(projectRoot, ...tempSkillDir.split('/'), ...file.relativePath.split('/')), file.content);
+        }
+        writeJsonFileInsideWithoutSymlinks(projectRoot, path.join(projectRoot, ...tempSkillDir.split('/'), PROVENANCE_FILE), {
+            schema_version: '1',
+            kind: 'external_skill_source',
+            source,
+            files: fileReport,
+            script_trust: scriptTrust,
+            warnings,
+        });
+        renameSync(targetPath, backupPath);
+        renameSync(tempPath, targetPath);
+        rmSync(backupPath, { recursive: true, force: true });
+    }
+    catch (error) {
+        rmSync(tempPath, { recursive: true, force: true });
+        if (!existsSync(targetPath) && existsSync(backupPath)) {
+            renameSync(backupPath, targetPath);
+        }
+        else {
+            rmSync(backupPath, { recursive: true, force: true });
+        }
+        throw error;
+    }
+}
 function rejectionReport(mode, issue) {
     return {
         schema_version: '1',
@@ -410,6 +843,199 @@ function rejectionReport(mode, issue) {
         wrote_files: false,
     };
 }
+function rejectedUpdateItem(skillName, issue) {
+    return {
+        skill_name: skillName,
+        ok: false,
+        status: 'rejected',
+        source: null,
+        target: createTarget(skillName),
+        current_files: [],
+        remote_files: [],
+        changed_files: [],
+        warnings: [],
+        issues: [issue],
+        wrote_files: false,
+    };
+}
+async function createExternalSkillUpdateItem(projectRoot, skillName, options) {
+    const target = createTarget(skillName);
+    try {
+        const provenance = readExternalSkillProvenance(projectRoot, skillName);
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        if (typeof fetchImpl !== 'function') {
+            throw new Error('This runtime does not provide fetch.');
+        }
+        const installedRelativeFilePaths = readInstalledRelativeFilePaths(projectRoot, target);
+        const installedFiles = readInstalledFileReports(projectRoot, target, provenance.files);
+        const driftIssues = localDriftIssues(skillName, provenance.files, installedFiles, installedRelativeFilePaths);
+        if (driftIssues.length > 0) {
+            return {
+                skill_name: skillName,
+                ok: false,
+                status: 'rejected',
+                source: provenance.source,
+                target,
+                current_files: installedFiles,
+                remote_files: [],
+                changed_files: [],
+                script_trust: provenance.script_trust,
+                warnings: [],
+                issues: driftIssues,
+                wrote_files: false,
+            };
+        }
+        const remoteSourceFiles = await loadExternalSkillFiles(fetchImpl, sourceToParsed(provenance.source));
+        const normalizedRemoteFiles = normalizeImportedSkillFiles(remoteSourceFiles);
+        const remoteReports = fileReports(normalizedRemoteFiles);
+        const changedFiles = collectFileChanges(provenance.files, remoteReports);
+        const mode = options.mode ?? (options.action === 'outdated' ? 'check' : 'install');
+        const trustScripts = options.action === 'update' && options.trustScripts === true;
+        const hasScriptFiles = remoteReports.some((file) => file.kind === 'script');
+        if (options.action === 'update' &&
+            mode === 'install' &&
+            hasScriptFiles &&
+            provenance.script_trust?.grants_command_authority === true &&
+            !trustScripts) {
+            return {
+                skill_name: skillName,
+                ok: false,
+                status: 'rejected',
+                source: provenance.source,
+                target,
+                current_files: installedFiles,
+                remote_files: remoteReports,
+                changed_files: changedFiles,
+                script_trust: provenance.script_trust,
+                warnings: [],
+                issues: [`External skill ${skillName} has trusted scripts; rerun update with --trust-scripts to refresh script files.`],
+                wrote_files: false,
+            };
+        }
+        const scriptTrust = createScriptTrust(projectRoot, target, remoteReports, trustScripts, mode === 'install' ? 'install' : 'dry_run', provenance.script_trust);
+        const warnings = [
+            ...(changedFiles.length === 0 ? ['External skill is already current.'] : []),
+            ...(hasScriptFiles && scriptTrust.status !== 'trusted'
+                ? ['Imported scripts are inert reference files; mustflow does not grant command authority for external scripts.']
+                : []),
+            ...(scriptTrust.status === 'trusted'
+                ? ['Imported scripts were trusted by request; mustflow created command-contract intents gated by network and destructive approvals.']
+                : []),
+            ...(scriptTrust.status === 'planned'
+                ? ['Imported scripts would be trusted by request during install; dry-run only reports the command-contract plan.']
+                : []),
+            'External skills are untrusted until the agent reads and evaluates the selected SKILL.md.',
+        ];
+        if (options.action === 'update' && mode === 'install' && changedFiles.length > 0) {
+            writeUpdatedSkillFiles(projectRoot, target, provenance.source, normalizedRemoteFiles, remoteReports, warnings, scriptTrust);
+            writeTrustedScriptCommandContract(projectRoot, target, provenance.source, scriptTrust);
+        }
+        return {
+            skill_name: skillName,
+            ok: true,
+            status: options.action === 'update' && mode === 'install' && changedFiles.length > 0
+                ? 'updated'
+                : changedFiles.length > 0
+                    ? 'outdated'
+                    : 'current',
+            source: provenance.source,
+            target,
+            current_files: installedFiles,
+            remote_files: remoteReports,
+            changed_files: changedFiles,
+            script_trust: scriptTrust,
+            warnings,
+            issues: [],
+            wrote_files: options.action === 'update' && mode === 'install' && changedFiles.length > 0,
+        };
+    }
+    catch (error) {
+        return rejectedUpdateItem(skillName, error instanceof Error ? error.message : String(error));
+    }
+}
+function selectedExternalSkillNames(projectRoot, options) {
+    if (options.all === true || (options.action === 'outdated' && (!options.skillNames || options.skillNames.length === 0))) {
+        return installedExternalSkillNames(projectRoot);
+    }
+    return [...new Set(options.skillNames ?? [])].sort((left, right) => left.localeCompare(right));
+}
+export async function createExternalSkillUpdateReport(projectRoot, options) {
+    const action = options.action;
+    const mode = action === 'outdated' ? 'check' : options.mode ?? 'install';
+    const checkState = createExternalSkillUpdateCheckState(projectRoot, options.now ?? new Date());
+    const warnings = [];
+    const issues = [];
+    if (action === 'update' && options.all !== true && (!options.skillNames || options.skillNames.length === 0)) {
+        issues.push('mf skill update requires a skill name or --all.');
+    }
+    if (options.all === true && options.skillNames && options.skillNames.length > 0) {
+        issues.push(`mf skill ${action} accepts either --all or skill names, not both.`);
+    }
+    if (action === 'update' && options.skillNames && options.skillNames.length > 1 && options.all !== true) {
+        issues.push('mf skill update accepts one skill name at a time unless --all is used.');
+    }
+    const requestedNames = selectedExternalSkillNames(projectRoot, options);
+    for (const skillName of requestedNames) {
+        if (!SLUG_PATTERN.test(skillName)) {
+            issues.push(`Invalid external skill name: ${skillName}`);
+        }
+    }
+    if (issues.length > 0) {
+        return {
+            schema_version: '1',
+            kind: 'skill_update_report',
+            command: 'skill',
+            action,
+            ok: false,
+            mode,
+            status: 'rejected',
+            check_state: checkState,
+            skills: [],
+            warnings,
+            issues,
+            wrote_files: false,
+        };
+    }
+    const installedNames = new Set(installedExternalSkillNames(projectRoot));
+    const missingNames = requestedNames.filter((name) => !installedNames.has(name));
+    const existingNames = requestedNames.filter((name) => installedNames.has(name));
+    const skills = [
+        ...missingNames.map((name) => rejectedUpdateItem(name, `External skill is not installed: ${name}`)),
+    ];
+    for (const skillName of existingNames) {
+        skills.push(await createExternalSkillUpdateItem(projectRoot, skillName, {
+            action,
+            mode,
+            trustScripts: options.trustScripts,
+            fetch: options.fetch,
+        }));
+    }
+    if (installedNames.size > 0 || requestedNames.length > 0) {
+        writeExternalSkillUpdateCheckState(projectRoot, checkState.checked_at);
+    }
+    const wroteFiles = skills.some((skill) => skill.wrote_files);
+    const ok = skills.every((skill) => skill.ok);
+    return {
+        schema_version: '1',
+        kind: 'skill_update_report',
+        command: 'skill',
+        action,
+        ok,
+        mode,
+        status: ok
+            ? wroteFiles
+                ? 'updated'
+                : mode === 'dry_run'
+                    ? 'preview'
+                    : 'checked'
+            : 'rejected',
+        check_state: checkState,
+        skills,
+        warnings,
+        issues: skills.flatMap((skill) => skill.issues),
+        wrote_files: wroteFiles,
+    };
+}
 export async function createExternalSkillImportReport(projectRoot, inputUrl, options) {
     const mode = options.mode;
     try {
@@ -424,14 +1050,31 @@ export async function createExternalSkillImportReport(projectRoot, inputUrl, opt
         const source = externalSkillSourceFromParsed(inputUrl, parsed);
         const files = normalizeImportedSkillFiles(sourceFiles);
         const reports = fileReports(files);
+        const scriptTrust = createScriptTrust(projectRoot, target, reports, options.trustScripts === true, mode);
         const warnings = [
-            ...(reports.some((file) => file.kind === 'script')
+            ...(reports.some((file) => file.kind === 'script') && scriptTrust.status !== 'trusted'
                 ? ['Imported scripts are inert reference files; mustflow does not grant command authority for external scripts.']
                 : []),
+            ...(scriptTrust.status === 'trusted'
+                ? ['Imported scripts were trusted by request; mustflow created command-contract intents gated by network and destructive approvals.']
+                : []),
+            ...(scriptTrust.status === 'planned'
+                ? ['Imported scripts would be trusted by request during install; dry-run only reports the command-contract plan.']
+                : []),
             'External skills are untrusted until the agent reads and evaluates the selected SKILL.md.',
         ];
         if (mode === 'install') {
-            writeImportedSkillFiles(projectRoot, target, source, files, reports, warnings);
+            try {
+                writeImportedSkillFiles(projectRoot, target, source, files, reports, warnings, scriptTrust);
+                writeTrustedScriptCommandContract(projectRoot, target, source, scriptTrust);
+            }
+            catch (error) {
+                rmSync(path.join(projectRoot, ...target.skill_dir.split('/')), { recursive: true, force: true });
+                if (scriptTrust.fragment_path) {
+                    rmSync(path.join(projectRoot, ...scriptTrust.fragment_path.split('/')), { force: true });
+                }
+                throw error;
+            }
         }
         return {
             schema_version: '1',
@@ -444,6 +1087,7 @@ export async function createExternalSkillImportReport(projectRoot, inputUrl, opt
             source,
             target,
             files: reports,
+            script_trust: scriptTrust,
             warnings,
             issues: [],
             wrote_files: mode === 'install',