@funnelsgrove/cli 0.1.14 → 0.1.18

package/dist/localSync.js

@@ -1,9 +1,32 @@
-import { createHash } from 'node:crypto';
-import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readdir, realpath, rename, rm, stat } from 'node:fs/promises';
 import path from 'node:path';
 export const SYNC_MANIFEST_FILE = '.funnelsgrove-sync.json';
 export const DEFAULT_PATCH_BATCH_CONTENT_CHARS = 12_000_000;
-const EXCLUDED_LOCAL_DIRECTORY_NAMES = ['.git', '.playwright-cli', 'node_modules', '.next', 'out', 'output'];
+export const DEFAULT_SOURCE_CANDIDATE_BATCH_CONTENT_BYTES = 12_000_000;
+export const MAX_SOURCE_CANDIDATE_OPERATIONS = 200 * 500;
+export const MAX_SOURCE_CANDIDATE_FILE_BYTES = 5 * 1024 * 1024;
+export const MAX_SOURCE_CANDIDATE_PATH_CHARACTERS = 1_024;
+export const MAX_SOURCE_CANDIDATE_TOTAL_BYTES = 100 * 1024 * 1024;
+const MAX_SOURCE_CANDIDATE_ATTEMPTS = 100;
+export async function runSyncDownLocalLifecycle(lifecycle) {
+    await lifecycle.recoverMigration();
+    await lifecycle.recoverDocs();
+    await lifecycle.refreshDocs();
+    await lifecycle.writeSyncState();
+}
+const EXCLUDED_LOCAL_DIRECTORY_NAMES = [
+    '.git',
+    '.funnelsgrove',
+    '.playwright-cli',
+    'node_modules',
+    '.next',
+    'coverage',
+    'dist',
+    'out',
+    'output',
+];
 const EXCLUDED_PATH_PARTS = new Set(EXCLUDED_LOCAL_DIRECTORY_NAMES);
 const LOCAL_ONLY_GITIGNORE_LINES = [
     '.env',
@@ -13,22 +36,152 @@ const LOCAL_ONLY_GITIGNORE_LINES = [
     SYNC_MANIFEST_FILE,
     ...EXCLUDED_LOCAL_DIRECTORY_NAMES.filter((directoryName) => directoryName !== '.git'),
 ];
+const isErrno = (error, code) => (error instanceof Error && 'code' in error && error.code === code);
+const assertContainedPath = (rootDir, targetPath) => {
+    const relative = path.relative(rootDir, targetPath);
+    if (relative === '' || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`))) {
+        return;
+    }
+    throw sourceCandidateInvariantError('Local sync path escaped the selected funnel directory.');
+};
+const resolveSafeRoot = async (rootDir, create) => {
+    let metadata;
+    try {
+        metadata = await lstat(rootDir);
+    }
+    catch (error) {
+        if (!create || !isErrno(error, 'ENOENT'))
+            throw error;
+        await mkdir(rootDir, { recursive: true });
+        metadata = await lstat(rootDir);
+    }
+    if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
+        throw sourceCandidateInvariantError('The selected funnel directory must be a real directory, not a symlink.');
+    }
+    return realpath(rootDir);
+};
+const assertSafeExistingPath = async (rootDir, relativePath, createParents) => {
+    const safePath = assertSafeSyncPath(relativePath);
+    const segments = safePath.split('/');
+    let current = rootDir;
+    for (const segment of segments.slice(0, -1)) {
+        current = path.join(current, segment);
+        let metadata;
+        try {
+            metadata = await lstat(current);
+        }
+        catch (error) {
+            if (!createParents || !isErrno(error, 'ENOENT'))
+                throw error;
+            await mkdir(current);
+            metadata = await lstat(current);
+        }
+        if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
+            throw sourceCandidateInvariantError(`Local sync path traverses a symlink: ${relativePath}`);
+        }
+    }
+    const absolutePath = path.join(rootDir, ...segments);
+    assertContainedPath(rootDir, absolutePath);
+    try {
+        const metadata = await lstat(absolutePath);
+        if (metadata.isSymbolicLink() || !metadata.isFile()) {
+            throw sourceCandidateInvariantError(`Local sync path is not a regular file: ${relativePath}`);
+        }
+    }
+    catch (error) {
+        if (!isErrno(error, 'ENOENT'))
+            throw error;
+    }
+    return absolutePath;
+};
+const assertOpenFileContained = async (rootDir, absolutePath, opened) => {
+    const openedStat = await opened.stat();
+    if (!openedStat.isFile()) {
+        throw sourceCandidateInvariantError('Local sync only accepts regular files.');
+    }
+    const resolvedPath = await realpath(absolutePath);
+    assertContainedPath(rootDir, resolvedPath);
+    const currentStat = await stat(resolvedPath);
+    if (openedStat.dev !== currentStat.dev || openedStat.ino !== currentStat.ino) {
+        throw sourceCandidateInvariantError('Local source changed while opening it. Retry the sync.');
+    }
+};
+const readSafeRootFile = async (rootDir, relativePath) => {
+    const resolvedRoot = await resolveSafeRoot(rootDir, false);
+    const absolutePath = await assertSafeExistingPath(resolvedRoot, relativePath, false);
+    let handle;
+    try {
+        handle = await open(absolutePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (isErrno(error, 'ELOOP')) {
+            throw sourceCandidateInvariantError(`Local sync path is a symlink: ${relativePath}`);
+        }
+        throw error;
+    }
+    try {
+        await assertOpenFileContained(resolvedRoot, absolutePath, handle);
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+};
+const writeSafeRootFile = async (rootDir, relativePath, content) => {
+    const resolvedRoot = await resolveSafeRoot(rootDir, true);
+    const absolutePath = await assertSafeExistingPath(resolvedRoot, relativePath, true);
+    const tempPath = path.join(path.dirname(absolutePath), `.${path.basename(absolutePath)}.fgrove-${randomUUID()}.tmp`);
+    let handle = null;
+    try {
+        handle = await open(tempPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o666);
+        await assertOpenFileContained(resolvedRoot, tempPath, handle);
+        await handle.writeFile(content);
+        await handle.sync();
+        await handle.close();
+        handle = null;
+        await assertSafeExistingPath(resolvedRoot, relativePath, true);
+        await rename(tempPath, absolutePath);
+        assertContainedPath(resolvedRoot, await realpath(absolutePath));
+    }
+    finally {
+        if (handle)
+            await handle.close().catch(() => undefined);
+        await rm(tempPath, { force: true }).catch(() => undefined);
+    }
+};
 export function normalizeSyncPath(filePath) {
     const normalized = path.posix.normalize(filePath.replaceAll('\\', '/'));
     return normalized.replace(/^(\.\/|\/)+/, '');
 }
+const sourceCandidateInvariantError = (reason) => Object.assign(new Error(reason), { code: 'FG-CANDIDATE-001' });
 function assertSafeSyncPath(filePath) {
-    const normalized = normalizeSyncPath(filePath);
-    if (!normalized || normalized === '.' || normalized.startsWith('../') || normalized.includes('/../')) {
-        throw new Error(`Unsafe sync path "${filePath}"`);
+    if (filePath.length === 0
+        || Array.from(filePath).length > MAX_SOURCE_CANDIDATE_PATH_CHARACTERS
+        || filePath !== filePath.trim()
+        || filePath.startsWith('/')
+        || filePath.endsWith('/')
+        || filePath.includes('\\')
+        || filePath.includes('//')
+        || /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(filePath)
+        || /%(?:2e|2f|5c)/i.test(filePath)
+        || /[\x00-\x1f\x7f]/.test(filePath)
+        || filePath.split('/').some((segment) => segment === '' || segment === '.' || segment === '..')) {
+        throw sourceCandidateInvariantError(`Unsafe sync path "${filePath}"`);
+    }
+    return filePath;
+}
+function assertSafeSyncTargetPath(filePath) {
+    const safePath = assertSafeSyncPath(filePath);
+    if (!shouldSyncFile(safePath)) {
+        throw sourceCandidateInvariantError(`Excluded local-only or generated sync path "${safePath}"`);
     }
-    return normalized;
+    return safePath;
 }
 export function shouldSyncFile(filePath) {
     const normalized = normalizeSyncPath(filePath);
     const parts = normalized.split('/');
     const fileName = parts.at(-1) ?? '';
-    if (parts.some((part) => EXCLUDED_PATH_PARTS.has(part))) {
+    if (parts.some((part) => EXCLUDED_PATH_PARTS.has(part.toLocaleLowerCase('en-US')))) {
         return false;
     }
     if (fileName === SYNC_MANIFEST_FILE) {
@@ -40,7 +193,8 @@ export function shouldSyncFile(filePath) {
     return true;
 }
 export async function buildSyncManifest(rootDir, input) {
-    const files = await collectSyncFiles(rootDir, rootDir);
+    const resolvedRoot = await resolveSafeRoot(rootDir, false);
+    const files = await collectSyncFiles(resolvedRoot, resolvedRoot);
     return {
         version: 1,
         workspaceId: input.workspaceId,
@@ -49,12 +203,27 @@ export async function buildSyncManifest(rootDir, input) {
         files: files.sort((left, right) => left.path.localeCompare(right.path)),
     };
 }
+export function buildCommittedSyncManifest(input) {
+    return {
+        version: 1,
+        workspaceId: input.workspaceId,
+        funnelId: input.funnelId,
+        draftVersionId: input.draftVersionId,
+        files: input.files.map((file) => ({ ...file })),
+    };
+}
 export async function writeSyncManifest(rootDir, manifest) {
-    await writeFile(path.join(rootDir, SYNC_MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
+    await writeSafeRootFile(rootDir, SYNC_MANIFEST_FILE, `${JSON.stringify(manifest, null, 2)}\n`);
 }
 export async function ensureGitignore(rootDir) {
-    const gitignorePath = path.join(rootDir, '.gitignore');
-    const existing = await readFile(gitignorePath, 'utf8').catch(() => '');
+    let existing = '';
+    try {
+        existing = (await readSafeRootFile(rootDir, '.gitignore')).toString('utf8');
+    }
+    catch (error) {
+        if (!isErrno(error, 'ENOENT'))
+            throw error;
+    }
     const lines = existing.split(/\r?\n/g).filter(Boolean);
     const seen = new Set(lines);
     for (const line of LOCAL_ONLY_GITIGNORE_LINES) {
@@ -62,19 +231,18 @@ export async function ensureGitignore(rootDir) {
             lines.push(line);
         }
     }
-    await writeFile(gitignorePath, `${lines.join('\n')}\n`, 'utf8');
+    await writeSafeRootFile(rootDir, '.gitignore', `${lines.join('\n')}\n`);
 }
 export async function writeLocalEnvFile(rootDir, envFile) {
     if (!envFile) {
         return false;
     }
-    await mkdir(rootDir, { recursive: true });
-    await writeFile(path.join(rootDir, '.env'), envFile, 'utf8');
+    await writeSafeRootFile(rootDir, '.env', envFile);
     return true;
 }
 export async function readSyncManifest(rootDir) {
     try {
-        const raw = JSON.parse(await readFile(path.join(rootDir, SYNC_MANIFEST_FILE), 'utf8'));
+        const raw = JSON.parse((await readSafeRootFile(rootDir, SYNC_MANIFEST_FILE)).toString('utf8'));
         if (raw.version !== 1 ||
             typeof raw.workspaceId !== 'string' ||
             typeof raw.funnelId !== 'string' ||
@@ -100,13 +268,19 @@ export async function readSyncManifest(rootDir) {
         throw error;
     }
 }
-export async function collectSourceFiles(rootDir) {
+export async function collectSourceSnapshot(rootDir) {
     const manifest = await buildSyncManifest(rootDir, {
         workspaceId: '',
         funnelId: '',
         draftVersionId: '',
     });
-    return readSourceFiles(rootDir, manifest.files);
+    return {
+        manifestFiles: manifest.files,
+        sourceFiles: await readSourceFiles(rootDir, manifest.files),
+    };
+}
+export async function collectSourceFiles(rootDir) {
+    return (await collectSourceSnapshot(rootDir)).sourceFiles;
 }
 export async function collectChangedSourceFiles(rootDir, previousManifest) {
     const currentManifest = await buildSyncManifest(rootDir, {
@@ -160,6 +334,199 @@ export function chunkChangedSourceFiles(changes, maxContentChars = DEFAULT_PATCH
     pushCurrentBatch();
     return batches;
 }
+export function buildSourceCandidateOperations(input) {
+    const previousPathByLower = new Map();
+    for (const file of input.previousFiles) {
+        const filePath = assertSafeSyncPath(file.path);
+        const lowerPath = filePath.toLowerCase();
+        if (previousPathByLower.has(lowerPath)) {
+            throw sourceCandidateInvariantError(`Source candidate has a case-colliding path: ${filePath}`);
+        }
+        previousPathByLower.set(lowerPath, filePath);
+    }
+    const deletedPathByLower = new Map();
+    for (const deletedPath of input.deletedPaths) {
+        const filePath = assertSafeSyncPath(deletedPath);
+        const lowerPath = filePath.toLowerCase();
+        if (deletedPathByLower.has(lowerPath)) {
+            throw sourceCandidateInvariantError(`Source candidate repeats a path: ${filePath}`);
+        }
+        deletedPathByLower.set(lowerPath, filePath);
+    }
+    const writtenPathByLower = new Map();
+    for (const file of input.files) {
+        const filePath = assertSafeSyncTargetPath(file.path);
+        const lowerPath = filePath.toLowerCase();
+        if (writtenPathByLower.has(lowerPath) || deletedPathByLower.has(lowerPath)) {
+            throw sourceCandidateInvariantError(`Source candidate repeats or case-collides at: ${filePath}`);
+        }
+        const previousPath = previousPathByLower.get(lowerPath);
+        if (previousPath !== undefined && previousPath !== filePath) {
+            throw sourceCandidateInvariantError(`Source candidate has a case-colliding path: ${filePath}`);
+        }
+        writtenPathByLower.set(lowerPath, filePath);
+    }
+    const finalPaths = new Set(Array.from(previousPathByLower.keys()).filter((filePath) => !deletedPathByLower.has(filePath)));
+    for (const filePath of writtenPathByLower.keys())
+        finalPaths.add(filePath);
+    if (finalPaths.size > 5_000) {
+        throw sourceCandidateInvariantError('Source candidate final snapshot exceeds 5,000 files.');
+    }
+    const deleted = Array.from(deletedPathByLower.values())
+        .sort((left, right) => left.localeCompare(right))
+        .map((filePath) => ({ type: 'delete', path: filePath }));
+    const changed = input.files
+        .map((file) => {
+        const filePath = assertSafeSyncTargetPath(file.path);
+        return {
+            type: previousPathByLower.has(filePath.toLowerCase()) ? 'modify' : 'create',
+            path: filePath,
+            content: file.content,
+            contentType: file.contentType,
+            sha256: createHash('sha256').update(file.content).digest('hex'),
+        };
+    })
+        .sort((left, right) => left.path.localeCompare(right.path));
+    return [...deleted, ...changed];
+}
+const sourceCandidateRequestHash = (input) => createHash('sha256').update(JSON.stringify(input)).digest('hex');
+const throwIfAborted = (signal) => {
+    if (!signal?.aborted)
+        return;
+    const error = new Error('Source candidate sync was canceled.');
+    error.name = 'AbortError';
+    throw error;
+};
+const assertSourceCandidateLimits = (operations) => {
+    if (operations.length > MAX_SOURCE_CANDIDATE_OPERATIONS) {
+        throw sourceCandidateInvariantError('Source candidate exceeds 200 batches of 500 operations.');
+    }
+    let totalBytes = 0;
+    const affectedPathByLower = new Map();
+    for (const operation of operations) {
+        const affectedPaths = operation.type === 'rename'
+            ? [assertSafeSyncPath(operation.oldPath), assertSafeSyncTargetPath(operation.path)]
+            : operation.type === 'delete'
+                ? [assertSafeSyncPath(operation.path)]
+                : [assertSafeSyncTargetPath(operation.path)];
+        for (const filePath of affectedPaths) {
+            const lowerPath = filePath.toLowerCase();
+            if (affectedPathByLower.has(lowerPath)) {
+                throw sourceCandidateInvariantError(`Source candidate repeats or case-collides at: ${filePath}`);
+            }
+            affectedPathByLower.set(lowerPath, filePath);
+        }
+        if (!('content' in operation))
+            continue;
+        const sizeBytes = Buffer.byteLength(operation.content, 'utf8');
+        if (sizeBytes > MAX_SOURCE_CANDIDATE_FILE_BYTES) {
+            throw sourceCandidateInvariantError(`Source candidate file exceeds 5 MiB: ${operation.path}`);
+        }
+        if (createHash('sha256').update(operation.content).digest('hex') !== operation.sha256) {
+            throw sourceCandidateInvariantError(`Source candidate hash does not match: ${operation.path}`);
+        }
+        totalBytes += sizeBytes;
+        if (totalBytes > MAX_SOURCE_CANDIDATE_TOTAL_BYTES) {
+            throw sourceCandidateInvariantError('Source candidate exceeds 100 MiB total content.');
+        }
+    }
+};
+export async function runSourceCandidateSync(input) {
+    const maxOperationsPerBatch = input.maxOperationsPerBatch ?? 500;
+    const maxContentBytesPerBatch = input.maxContentBytesPerBatch
+        ?? DEFAULT_SOURCE_CANDIDATE_BATCH_CONTENT_BYTES;
+    const message = input.message?.trim() || undefined;
+    if (input.operations.length === 0
+        || !Number.isInteger(maxOperationsPerBatch)
+        || maxOperationsPerBatch < 1
+        || maxOperationsPerBatch > 500
+        || !Number.isInteger(maxContentBytesPerBatch)
+        || maxContentBytesPerBatch < 1) {
+        throw new Error('Source candidate sync requires operations in batches of 1 to 500.');
+    }
+    if (message && message.length > 200) {
+        throw sourceCandidateInvariantError('Source candidate message exceeds 200 characters.');
+    }
+    assertSourceCandidateLimits(input.operations);
+    throwIfAborted(input.signal);
+    const requestHash = sourceCandidateRequestHash({
+        workspaceId: input.workspaceId,
+        funnelId: input.funnelId,
+        baseDraftVersionId: input.baseDraftVersionId,
+        message,
+        operations: input.operations,
+    });
+    const baseIdempotencyKey = `cli-sync:${requestHash}`;
+    let begin = null;
+    for (let attempt = 1; attempt <= MAX_SOURCE_CANDIDATE_ATTEMPTS; attempt += 1) {
+        const receipt = await input.api.begin({
+            workspaceId: input.workspaceId,
+            funnelId: input.funnelId,
+            baseDraftVersionId: input.baseDraftVersionId,
+            idempotencyKey: attempt === 1
+                ? baseIdempotencyKey
+                : `${baseIdempotencyKey}:attempt:${attempt}`,
+        });
+        if (!receipt.candidateId || receipt.baseDraftVersionId !== input.baseDraftVersionId) {
+            throw sourceCandidateInvariantError('Source candidate begin receipt does not match the requested transaction.');
+        }
+        if (receipt.status === 'aborted' || receipt.status === 'expired' || receipt.status === 'failed') {
+            continue;
+        }
+        begin = receipt;
+        break;
+    }
+    if (!begin) {
+        throw sourceCandidateInvariantError('Source candidate begin receipt does not match the requested transaction.');
+    }
+    try {
+        const batches = [];
+        let batch = [];
+        let batchContentBytes = 0;
+        for (const operation of input.operations) {
+            const contentBytes = 'content' in operation
+                ? Buffer.byteLength(operation.content, 'utf8')
+                : 0;
+            if (batch.length > 0
+                && (batch.length >= maxOperationsPerBatch
+                    || batchContentBytes + contentBytes > maxContentBytesPerBatch)) {
+                batches.push(batch);
+                batch = [];
+                batchContentBytes = 0;
+            }
+            batch.push(operation);
+            batchContentBytes += contentBytes;
+        }
+        if (batch.length > 0)
+            batches.push(batch);
+        if (begin.status === 'staging') {
+            for (const [index, operations] of batches.entries()) {
+                throwIfAborted(input.signal);
+                await input.api.stage({
+                    workspaceId: input.workspaceId,
+                    candidateId: begin.candidateId,
+                    idempotencyKey: `cli-sync:${requestHash}:stage:${index + 1}`,
+                    operations,
+                });
+            }
+        }
+        throwIfAborted(input.signal);
+        return await input.api.finalize({
+            workspaceId: input.workspaceId,
+            candidateId: begin.candidateId,
+            message,
+        });
+    }
+    catch (error) {
+        if (begin.status === 'staging') {
+            await input.api.abort({
+                workspaceId: input.workspaceId,
+                candidateId: begin.candidateId,
+            }).catch(() => undefined);
+        }
+        throw error;
+    }
+}
 export function formatSyncUploadSummary(changes, largestFileLimit = 5) {
     const fileSizes = changes.files
         .map((file) => ({
@@ -197,24 +564,24 @@ function formatByteSize(byteCount) {
 }
 async function readSourceFiles(rootDir, manifestFiles) {
     const files = await Promise.all(manifestFiles.map(async (file) => {
-        const absolutePath = path.join(rootDir, assertSafeSyncPath(file.path));
-        const imageContentType = inferImageContentType(file.path);
-        const buffer = await readFile(absolutePath);
+        const binaryContentType = inferBinaryContentType(file.path);
+        const buffer = await readSafeRootFile(rootDir, file.path);
+        if (createHash('sha256').update(buffer).digest('hex') !== file.hash) {
+            throw sourceCandidateInvariantError(`Local source changed while preparing the candidate: ${file.path}. Retry the sync.`);
+        }
         return {
             path: file.path,
-            content: imageContentType ? `data:${imageContentType};base64,${buffer.toString('base64')}` : buffer.toString('utf8'),
-            contentType: imageContentType || 'text/plain',
+            content: binaryContentType ? `data:${binaryContentType};base64,${buffer.toString('base64')}` : buffer.toString('utf8'),
+            contentType: binaryContentType || 'text/plain',
         };
     }));
     return files.sort((left, right) => left.path.localeCompare(right.path));
 }
 export async function writeSourceFiles(rootDir, files) {
     for (const file of files) {
-        const relativePath = assertSafeSyncPath(file.path);
-        const absolutePath = path.join(rootDir, relativePath);
-        await mkdir(path.dirname(absolutePath), { recursive: true });
+        const relativePath = assertSafeSyncTargetPath(file.path);
         const decodedContent = decodeBinarySourceContent(file);
-        await writeFile(absolutePath, decodedContent || file.content, decodedContent ? undefined : 'utf8');
+        await writeSafeRootFile(rootDir, relativePath, decodedContent || file.content);
     }
 }
 async function collectSyncFiles(rootDir, dir) {
@@ -226,43 +593,51 @@ async function collectSyncFiles(rootDir, dir) {
         if (!shouldSyncFile(relativePath)) {
             continue;
         }
-        if (entry.isDirectory()) {
+        const metadata = await lstat(absolutePath);
+        if (metadata.isSymbolicLink()) {
+            throw sourceCandidateInvariantError(`Local sync path is a symlink: ${relativePath}`);
+        }
+        if (metadata.isDirectory()) {
             files.push(...(await collectSyncFiles(rootDir, absolutePath)));
             continue;
         }
-        if (entry.isFile() || (entry.isSymbolicLink() && (await stat(absolutePath)).isFile())) {
+        if (metadata.isFile()) {
             files.push({
                 path: relativePath,
-                hash: await hashFile(absolutePath),
+                hash: await hashFile(rootDir, relativePath),
             });
         }
     }
     return files;
 }
-async function hashFile(filePath) {
-    return createHash('sha256').update(await readFile(filePath)).digest('hex');
+async function hashFile(rootDir, relativePath) {
+    return createHash('sha256').update(await readSafeRootFile(rootDir, relativePath)).digest('hex');
 }
-function inferImageContentType(filePath) {
-    const extension = path.extname(filePath).toLowerCase();
-    if (extension === '.png') {
-        return 'image/png';
-    }
-    if (extension === '.jpg' || extension === '.jpeg') {
-        return 'image/jpeg';
-    }
-    if (extension === '.webp') {
-        return 'image/webp';
-    }
-    if (extension === '.gif') {
-        return 'image/gif';
-    }
-    if (extension === '.svg') {
-        return 'image/svg+xml';
-    }
-    if (extension === '.avif') {
-        return 'image/avif';
-    }
-    return null;
+const BINARY_CONTENT_TYPE_BY_EXTENSION = {
+    '.aac': 'audio/aac',
+    '.avif': 'image/avif',
+    '.flac': 'audio/flac',
+    '.gif': 'image/gif',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.m4a': 'audio/mp4',
+    '.m4v': 'video/mp4',
+    '.mov': 'video/quicktime',
+    '.mp3': 'audio/mpeg',
+    '.mp4': 'video/mp4',
+    '.oga': 'audio/ogg',
+    '.ogg': 'audio/ogg',
+    '.ogv': 'video/ogg',
+    '.opus': 'audio/ogg',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml',
+    '.wav': 'audio/wav',
+    '.weba': 'audio/webm',
+    '.webm': 'video/webm',
+    '.webp': 'image/webp',
+};
+function inferBinaryContentType(filePath) {
+    return BINARY_CONTENT_TYPE_BY_EXTENSION[path.extname(filePath).toLowerCase()] || null;
 }
 function decodeDataUrl(content) {
     const match = content.trim().match(/^data:([^;,]+);base64,([A-Za-z0-9+/=\s_-]+)$/);

package/dist/projectValidator.d.ts

@@ -0,0 +1,27 @@
+import { type FunnelValidationResult } from './diagnosticOutput.js';
+export declare const PROJECT_VALIDATOR_TIMEOUT_MS = 120000;
+export declare const PROJECT_VALIDATOR_CONTRACT_VERSION: 3;
+export type ProjectValidatorProcessRequest = {
+    command: 'npm';
+    args: ['run', 'validate:funnel', '--', '--json'];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    timeoutMs: number;
+};
+export type ProjectValidatorProcessResult = {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    timedOut: boolean;
+    error?: unknown;
+};
+export type ProjectValidatorProcess = (request: ProjectValidatorProcessRequest) => Promise<ProjectValidatorProcessResult>;
+export type RunProjectValidatorOptions = {
+    projectDir: string;
+    parentEnv?: NodeJS.ProcessEnv;
+    runProcess?: ProjectValidatorProcess;
+    timeoutMs?: number;
+};
+export declare const buildProjectValidatorEnvironment: (parentEnv: NodeJS.ProcessEnv) => NodeJS.ProcessEnv;
+export declare const runProjectValidator: (options: RunProjectValidatorOptions) => Promise<FunnelValidationResult>;