@chalksurf/cli 0.2.3 → 0.2.4

package/dist/commands/sheet.js

@@ -1,772 +0,0 @@
-import { z } from 'zod';
-import { createApiClient } from '../lib/api-client.js';
-import { CliCommandError } from '../lib/cli-error.js';
-import { normalizeLimit, normalizeOffset, normalizeOptionalText, normalizeOwnership, toApiOwnership, } from '../lib/command-options.js';
-import { buildFileImportCommandSources, buildFileImportFormData, normalizeWaitTimeoutMs } from '../lib/import-files.js';
-import { buildCliImportSources, formatCliImportSummary, formatCliImportTranslationJobs, summarizeCliImportJobs, } from '../lib/import-output.js';
-import { loadExerciseSheetSolutionImportManifest, loadSheetImportManifest, } from '../lib/manifest.js';
-import { createResolvedApiClient, mapApiErrorToCliError, requireResolvedBaseUrl, requireResolvedToken, resolveRequestedOrganizationId, } from '../lib/session.js';
-import { cleanupResolvedSources, resolveSources } from '../lib/source-resolver.js';
-import { resolveRequestedTranslateToLanguages, translationLanguages, } from '../lib/translation-languages.js';
-import { formatCliJobSummary, getWaitError, getWaitExitCode, throwSilentExitCode, waitForCliJobs, } from '../lib/user-jobs.js';
-const hasUniqueItems = (values) => new Set(values).size === values.length;
-const sheetImportComponentIdPattern = /^[a-zA-Z0-9_-]{1,80}$/;
-const isValidTargetFolderPath = (value) => {
-    const normalizedSegments = value
-        .replaceAll('\\', '/')
-        .split('/')
-        .filter((segment) => segment.length > 0);
-    return normalizedSegments.length > 0 && normalizedSegments.every((segment) => segment !== '.' && segment !== '..');
-};
-const assertValidSheetImportPlan = (plan) => {
-    if (plan.sheets.length === 0) {
-        throw new CliCommandError('Invalid sheet import plan: sheets must include at least one sheet.', 2);
-    }
-    plan.sheets.forEach((sheet) => {
-        if (sheet.sourceIndexes.length === 0) {
-            throw new CliCommandError('Invalid sheet import plan: sourceIndexes must include at least one source.', 2);
-        }
-        if (!sheet.sourceIndexes.every((sourceIndex) => Number.isInteger(sourceIndex) && sourceIndex >= 0)) {
-            throw new CliCommandError('Invalid sheet import plan: sourceIndexes must contain only non-negative integers.', 2);
-        }
-        if (!hasUniqueItems(sheet.sourceIndexes)) {
-            throw new CliCommandError('Invalid sheet import plan: sourceIndexes must be unique within a sheet.', 2);
-        }
-        if (sheet.components) {
-            if (sheet.targetFolderPath !== undefined || sheet.titleOverride !== undefined || sheet.translateToLanguages) {
-                throw new CliCommandError('Invalid sheet import plan: targetFolderPath, titleOverride, and translateToLanguages must be set on components when components are provided.', 2);
-            }
-            if (!hasUniqueItems(sheet.components.map((component) => component.componentId))) {
-                throw new CliCommandError('Invalid sheet import plan: componentId values must be unique within a sheet.', 2);
-            }
-            sheet.components.forEach((component) => {
-                if (!sheetImportComponentIdPattern.test(component.componentId)) {
-                    throw new CliCommandError('Invalid sheet import plan: componentId must be 1-80 letters, numbers, underscores, or hyphens.', 2);
-                }
-                if (!component.description.trim()) {
-                    throw new CliCommandError('Invalid sheet import plan: component descriptions must be non-empty.', 2);
-                }
-                if (component.targetFolderPath != null && !isValidTargetFolderPath(component.targetFolderPath)) {
-                    throw new CliCommandError('Invalid sheet import plan: component targetFolderPath must be a normalized folder path without "." or ".." segments.', 2);
-                }
-                if (component.translateToLanguages && !hasUniqueItems(component.translateToLanguages)) {
-                    throw new CliCommandError('Invalid sheet import plan: component translateToLanguages must be unique.', 2);
-                }
-            });
-            return;
-        }
-        if (sheet.targetFolderPath === undefined) {
-            throw new CliCommandError('Invalid sheet import plan: targetFolderPath is required.', 2);
-        }
-        if (sheet.targetFolderPath !== null && !isValidTargetFolderPath(sheet.targetFolderPath)) {
-            throw new CliCommandError('Invalid sheet import plan: targetFolderPath must be a normalized folder path without "." or ".." segments.', 2);
-        }
-        if (sheet.translateToLanguages && !hasUniqueItems(sheet.translateToLanguages)) {
-            throw new CliCommandError('Invalid sheet import plan: translateToLanguages must be unique.', 2);
-        }
-    });
-};
-const normalizeOptionalTitle = (value) => {
-    const normalizedValue = value?.trim();
-    if (!normalizedValue) {
-        return undefined;
-    }
-    return normalizedValue;
-};
-const normalizeOptionalTargetFolderPath = (value) => {
-    const normalizedValue = value?.trim();
-    if (!normalizedValue) {
-        return null;
-    }
-    return normalizedValue;
-};
-const resolveRequestedUuid = ({ flagValue, fallbackValue, label, required = false, }) => {
-    const resolvedValue = flagValue?.trim() || fallbackValue?.trim();
-    if (!resolvedValue) {
-        if (required) {
-            throw new CliCommandError(`${label} is required.`, 2);
-        }
-        return undefined;
-    }
-    const parsedValue = z.uuid().safeParse(resolvedValue);
-    if (!parsedValue.success) {
-        throw new CliCommandError(`${label} must be a valid UUID.`, 2);
-    }
-    return parsedValue.data;
-};
-const getFolderPathFromRelativePath = (relativePath) => {
-    const normalizedSegments = relativePath
-        .replaceAll('\\', '/')
-        .split('/')
-        .filter((segment) => segment.length > 0);
-    if (normalizedSegments.length <= 1) {
-        return null;
-    }
-    return normalizedSegments.slice(0, -1).join('/');
-};
-const assertSheetImportFlagUsage = ({ manifestPath, singleSheet, sources, targetFolderPath, title, translateTo, }) => {
-    if (manifestPath && singleSheet) {
-        throw new CliCommandError('--single-sheet cannot be used with --manifest. Define grouped sheet imports in the manifest.', 2);
-    }
-    if (manifestPath && targetFolderPath !== null) {
-        throw new CliCommandError('--target-folder cannot be used with --manifest. Set targetFolderPath in the manifest.', 2);
-    }
-    if (targetFolderPath !== null && !singleSheet) {
-        throw new CliCommandError('--target-folder can only be used with --single-sheet.', 2);
-    }
-    if (!title && !translateTo) {
-        return;
-    }
-    if (manifestPath) {
-        throw new CliCommandError('--title and --translate-to cannot be used with --manifest. Set the import metadata in the manifest instead.', 2);
-    }
-    if (!singleSheet && (sources.length !== 1 || sources[0]?.kind === 'directory')) {
-        throw new CliCommandError('--title and --translate-to can only be used with a single non-directory source. Use --manifest for multi-source imports.', 2);
-    }
-};
-const buildSheetImportSources = ({ sources, title, translateTo, }) => {
-    if (!title && !translateTo) {
-        return sources;
-    }
-    return sources.map((source, index) => {
-        if (index !== 0) {
-            return source;
-        }
-        return {
-            ...source,
-            title,
-            translateTo,
-        };
-    });
-};
-const buildSourceIndexesByInputIndex = (sources) => {
-    const sourceIndexesByInputIndex = new Map();
-    sources.forEach((source) => {
-        const sourceIndexes = sourceIndexesByInputIndex.get(source.sourceInputIndex) ?? [];
-        sourceIndexes.push(source.sourceIndex);
-        sourceIndexesByInputIndex.set(source.sourceInputIndex, sourceIndexes);
-    });
-    return sourceIndexesByInputIndex;
-};
-const resolveGroupedSourceIndexes = ({ groups, sourceIndexesByInputIndex, }) => {
-    return groups.map((group, groupIndex) => {
-        const sourceIndexes = group.sourceInputIndexes.flatMap((sourceInputIndex) => {
-            const resolvedSourceIndexes = sourceIndexesByInputIndex.get(sourceInputIndex);
-            if (!resolvedSourceIndexes || resolvedSourceIndexes.length === 0) {
-                throw new CliCommandError(`Manifest sheet at index ${groupIndex} references source index ${sourceInputIndex}, but it resolved to no files.`, 2);
-            }
-            return resolvedSourceIndexes;
-        });
-        return {
-            sourceIndexes,
-            ...(group.components
-                ? {
-                    components: group.components.map((component) => ({
-                        componentId: component.componentId,
-                        description: component.description,
-                        targetFolderPath: component.targetFolderPath,
-                        titleOverride: component.title,
-                        translateToLanguages: component.translateTo,
-                    })),
-                }
-                : {
-                    targetFolderPath: group.targetFolderPath,
-                    titleOverride: group.title,
-                    translateToLanguages: group.translateTo,
-                }),
-        };
-    });
-};
-const buildSheetImportPlan = ({ groupedManifestSheets, requestedTargetFolderPath, requestedTitle, requestedTranslateTo, singleSheet, sources, }) => {
-    const sourceIndexesByInputIndex = buildSourceIndexesByInputIndex(sources);
-    const rawPlan = groupedManifestSheets
-        ? {
-            sheets: resolveGroupedSourceIndexes({
-                groups: groupedManifestSheets,
-                sourceIndexesByInputIndex,
-            }),
-        }
-        : singleSheet
-            ? {
-                sheets: [
-                    {
-                        sourceIndexes: sources.map((source) => source.sourceIndex),
-                        targetFolderPath: requestedTargetFolderPath,
-                        titleOverride: requestedTitle,
-                        translateToLanguages: requestedTranslateTo,
-                    },
-                ],
-            }
-            : {
-                sheets: sources.map((source) => ({
-                    sourceIndexes: [source.sourceIndex],
-                    targetFolderPath: getFolderPathFromRelativePath(source.relativePath),
-                    titleOverride: source.title,
-                    translateToLanguages: source.translateTo,
-                })),
-            };
-    assertValidSheetImportPlan(rawPlan);
-    return rawPlan;
-};
-const buildSheetImportJobs = ({ importResultJobs, sources, waitedJobsById, }) => {
-    return importResultJobs.map((job, index) => {
-        const sourceIndexes = job.sourceIndexes ?? (sources[index] ? [sources[index].sourceIndex] : []);
-        const waitedJob = waitedJobsById?.get(job.jobId);
-        const importedSheetTranslationJobs = waitedJob?.sheets?.flatMap((sheet) => (sheet.status === 'imported' ? (sheet.translationJobs ?? []) : [])) ?? [];
-        return {
-            jobId: job.jobId,
-            sourceIndexes,
-            sourceIds: Array.from(new Set(sourceIndexes
-                .map((sourceIndex) => sources[sourceIndex]?.sourceId)
-                .filter((sourceId) => sourceId != null))),
-            status: waitedJob?.status ?? 'queued',
-            error: waitedJob?.error,
-            componentIds: job.componentIds,
-            exerciseSheetId: waitedJob?.exerciseSheetId,
-            sheets: waitedJob?.sheets,
-            translationJobs: waitedJob?.translationJobs ?? importedSheetTranslationJobs,
-        };
-    });
-};
-const buildSheetImportRequest = ({ inputMode, organizationId, timeoutMs, wait, }) => {
-    return {
-        organizationId,
-        inputMode,
-        wait,
-        timeoutMs,
-        target: {},
-    };
-};
-const buildSheetSolutionImportRequest = ({ exerciseSheetId, inputMode, organizationId, timeoutMs, wait, }) => {
-    return {
-        organizationId,
-        inputMode,
-        wait,
-        timeoutMs,
-        target: { exerciseSheetId },
-    };
-};
-const buildQueuedSheetSolutionImportJob = ({ jobId, sources, }) => {
-    return {
-        jobId,
-        sourceIndexes: sources.map((source) => source.sourceIndex),
-        sourceIds: sources.map((source) => source.sourceId).filter((sourceId) => sourceId !== null),
-        status: 'queued',
-    };
-};
-const buildWaitedSheetSolutionImportJob = ({ jobId, sources, waitedJob, }) => {
-    return {
-        jobId,
-        sourceIndexes: sources.map((source) => source.sourceIndex),
-        sourceIds: sources.map((source) => source.sourceId).filter((sourceId) => sourceId !== null),
-        status: waitedJob?.status ?? 'pending',
-        error: waitedJob?.error,
-        eligibleExerciseCount: waitedJob?.eligibleExerciseCount,
-        exerciseSheetId: waitedJob?.exerciseSheetId,
-        nonUpdatableExerciseCount: waitedJob?.nonUpdatableExerciseCount,
-        skippedExerciseCount: waitedJob?.skippedExerciseCount,
-        unmatchedImportedSolutionCount: waitedJob?.unmatchedImportedSolutionCount,
-        updatedExerciseCount: waitedJob?.updatedExerciseCount,
-    };
-};
-const formatSheetJobSourceLabel = ({ job, sources, }) => {
-    if (job.sourceIndexes.length !== 1) {
-        return `${job.sourceIndexes.length} source${job.sourceIndexes.length === 1 ? '' : 's'}`;
-    }
-    const firstSource = sources[job.sourceIndexes[0]];
-    return firstSource?.relativePath ?? 'unknown source';
-};
-const formatQueuedImportOutput = ({ jobs, summary, sources, }) => {
-    return [
-        `Queued ${jobs.length} import${jobs.length === 1 ? '' : 's'}.`,
-        ...jobs.map((job) => `${job.jobId}  ${formatSheetJobSourceLabel({ job, sources })}`),
-        jobs.length > 1 ? formatCliImportSummary(summary) : null,
-    ]
-        .filter(Boolean)
-        .join('\n');
-};
-const formatWaitedImportOutput = ({ jobs, summary, }) => {
-    return [
-        `${jobs.length} job${jobs.length === 1 ? '' : 's'} queued.`,
-        ...jobs.flatMap((job) => [
-            formatCliJobSummary({
-                id: job.jobId,
-                status: job.status === 'queued' ? 'pending' : job.status,
-                type: 'exercise_sheet_import',
-                createdAt: '',
-                updatedAt: '',
-                error: job.error,
-                exerciseSheetId: job.exerciseSheetId,
-                sheets: job.sheets,
-            }),
-            ...formatCliImportTranslationJobs(job.translationJobs),
-        ]),
-        jobs.length > 1 ? formatCliImportSummary(summary) : null,
-    ]
-        .filter(Boolean)
-        .join('\n');
-};
-const formatQueuedSheetSolutionImportOutput = (job) => {
-    return [
-        'Queued exercise sheet solution import.',
-        `${job.jobId}  ${job.sourceIndexes.length} source${job.sourceIndexes.length === 1 ? '' : 's'}`,
-    ].join('\n');
-};
-const formatWaitedSheetSolutionImportOutput = (job) => {
-    return formatCliJobSummary({
-        id: job.jobId,
-        status: job.status === 'queued' ? 'pending' : job.status,
-        type: 'exercise_sheet_solution_import',
-        createdAt: '',
-        updatedAt: '',
-        error: job.error,
-        exerciseSheetId: job.exerciseSheetId,
-    });
-};
-const formatSheetSearchOutput = ({ exerciseSheets, totalCount, }) => {
-    if (exerciseSheets.length === 0) {
-        return 'No sheets found.';
-    }
-    return [
-        `${exerciseSheets.length} of ${totalCount} sheet${totalCount === 1 ? '' : 's'} returned.`,
-        ...exerciseSheets.map((sheet) => `${sheet.id}  ${sheet.name}  ${sheet.exerciseCount} exercises`),
-    ].join('\n');
-};
-export const registerSheetCommands = (sheetYargs, context) => {
-    return sheetYargs
-        .command('search', 'Search exercise sheets visible to the selected organization', (searchYargs) => searchYargs
-        .option('text', {
-        type: 'string',
-        describe: 'Search sheet names',
-    })
-        .option('ownership', {
-        type: 'string',
-        default: 'own',
-        describe: 'Visibility scope: own, public, or all',
-    })
-        .option('limit', {
-        type: 'number',
-        default: 20,
-        describe: 'Maximum number of sheets to return',
-    })
-        .option('offset', {
-        type: 'number',
-        default: 0,
-        describe: 'Number of matching sheets to skip',
-    })
-        .example('chalksurf sheet search --text "OKTV 2014" --ownership own --json', 'Verify an imported private sheet in the selected organization')
-        .example('chalksurf --profile prod-codex sheet search --ownership own --limit 10 --json', 'List recent sheets visible to the agent profile'), async (argv) => {
-        const text = normalizeOptionalText(argv.text);
-        const ownership = normalizeOwnership(argv.ownership);
-        const limit = normalizeLimit(argv.limit);
-        const offset = normalizeOffset(argv.offset);
-        const { apiClient, organizationId } = await createResolvedApiClient({
-            context,
-            baseUrlFlagValue: argv.baseUrl,
-            organizationFlagValue: argv.organization,
-            profileName: argv.profile,
-        });
-        let searchResult;
-        try {
-            searchResult = await apiClient.searchExerciseSheets({
-                text,
-                ownership: toApiOwnership(ownership),
-                limit,
-                offset,
-            });
-        }
-        catch (error) {
-            throw mapApiErrorToCliError(error);
-        }
-        context.output.print({
-            request: {
-                text,
-                ownership,
-                limit,
-                offset,
-                organizationId: organizationId ?? null,
-            },
-            exerciseSheets: searchResult.exerciseSheets,
-            totalCount: searchResult.totalCount,
-        }, (result) => formatSheetSearchOutput({
-            exerciseSheets: result.exerciseSheets,
-            totalCount: result.totalCount,
-        }), {
-            command: 'sheet search',
-        });
-    })
-        .command('import [sources..]', 'Import one or more exercise sheet sources', (importYargs) => importYargs
-        .positional('sources', {
-        array: true,
-        type: 'string',
-        describe: 'Local file paths, directories, or HTTP(S) URLs',
-    })
-        .option('manifest', {
-        type: 'string',
-        describe: 'Load sources from a manifest file, or "-" for stdin',
-    })
-        .option('relative-path', {
-        type: 'string',
-        describe: 'Override the relative path for a single positional source',
-    })
-        .option('single-sheet', {
-        type: 'boolean',
-        default: false,
-        describe: 'Import all positional sources into one sheet',
-    })
-        .option('target-folder', {
-        type: 'string',
-        describe: 'Place a --single-sheet import into this destination folder (defaults to root)',
-    })
-        .option('title', {
-        type: 'string',
-        describe: 'Override the imported title for a single-sheet import',
-    })
-        .option('translate-to', {
-        array: true,
-        type: 'string',
-        describe: `Generate translated sheet content for these languages (${translationLanguages.join(', ')})`,
-    })
-        .option('timeout-ms', {
-        type: 'number',
-        default: 300000,
-        describe: 'Maximum time to wait before timing out',
-    })
-        .option('wait', {
-        type: 'boolean',
-        default: false,
-        describe: 'Wait for the queued jobs to finish',
-    })
-        .example('chalksurf sheet import ./fixtures/algebra.pdf --title "OKTV 2014 Round 1" --translate-to english --wait', 'Import a sheet, override its title, and request an English translation')
-        .example('chalksurf sheet import ./fixtures/round-1-a.pdf ./fixtures/round-1-b.pdf --single-sheet --target-folder Contests --wait', 'Import multiple source files into one sheet and place the result into a target folder')
-        .example('cat sheet-import.json | chalksurf --profile prod-codex sheet import --manifest - --wait --json', 'Drive multi-source sheet imports from a manifest in an agent or CI flow')
-        .epilogue([
-        'When --wait is set, the command exits after the queued import job reaches a terminal state.',
-        'For translated sheet imports, requested translations continue as separate jobs listed in the import result.',
-    ].join('\n')), async (argv) => {
-        const config = await context.configStore.loadProfile({ profileName: argv.profile });
-        const rawSources = (argv.sources ?? []).map(String);
-        const manifestPath = argv.manifest === '' ? '-' : argv.manifest;
-        const normalizedRawSources = manifestPath === '-' && rawSources[0] === '-' ? rawSources.slice(1) : rawSources;
-        const resolvedBaseUrl = requireResolvedBaseUrl({
-            flagValue: argv.baseUrl,
-            env: context.env,
-            config,
-        });
-        const resolvedToken = requireResolvedToken({
-            env: context.env,
-            config,
-        });
-        const commandSources = await buildFileImportCommandSources({
-            cwd: context.cwd,
-            loadManifest: loadSheetImportManifest,
-            manifestPath,
-            rawSources: normalizedRawSources,
-            relativePath: argv.relativePath,
-            stdin: context.stdin,
-            wait: argv.wait,
-        });
-        const requestedTitle = normalizeOptionalTitle(argv.title);
-        const requestedTranslateTo = resolveRequestedTranslateToLanguages(argv.translateTo);
-        const requestedTargetFolderPath = normalizeOptionalTargetFolderPath(argv.targetFolder);
-        const singleSheet = argv.singleSheet === true;
-        assertSheetImportFlagUsage({
-            manifestPath,
-            singleSheet,
-            sources: commandSources.sources,
-            targetFolderPath: requestedTargetFolderPath,
-            title: requestedTitle,
-            translateTo: requestedTranslateTo,
-        });
-        const sheetSources = buildSheetImportSources({
-            sources: commandSources.sources,
-            title: requestedTitle,
-            translateTo: requestedTranslateTo,
-        });
-        const organizationId = resolveRequestedOrganizationId({
-            flagValue: argv.organization,
-            fallbackValue: commandSources.organizationId,
-            env: context.env,
-            config,
-        });
-        const apiClient = createApiClient({
-            baseUrl: resolvedBaseUrl.value,
-            token: resolvedToken.value,
-            organizationId,
-        });
-        let resolvedSources = [];
-        try {
-            resolvedSources = await resolveSources({
-                cwd: context.cwd,
-                sources: sheetSources,
-            });
-            const sources = buildCliImportSources({
-                resolvedSources,
-                getExtra: (resolvedSource) => ({
-                    title: resolvedSource.sourceInput.title,
-                    translateTo: resolvedSource.sourceInput.translateTo,
-                }),
-            });
-            const formData = await buildFileImportFormData(resolvedSources);
-            const sheetImportPlan = buildSheetImportPlan({
-                groupedManifestSheets: commandSources.sheetGroups,
-                requestedTargetFolderPath,
-                requestedTitle,
-                requestedTranslateTo,
-                singleSheet,
-                sources,
-            });
-            formData.set('sheetImportPlan', JSON.stringify(sheetImportPlan));
-            const request = buildSheetImportRequest({
-                inputMode: manifestPath ? 'manifest' : 'arguments',
-                organizationId: organizationId ?? null,
-                timeoutMs: commandSources.wait ? normalizeWaitTimeoutMs(argv.timeoutMs) : null,
-                wait: commandSources.wait,
-            });
-            let importResult;
-            try {
-                importResult = await apiClient.importExerciseSheet(formData);
-            }
-            catch (error) {
-                throw mapApiErrorToCliError(error);
-            }
-            if (!commandSources.wait) {
-                const jobs = buildSheetImportJobs({
-                    importResultJobs: importResult.jobs,
-                    sources,
-                });
-                const summary = summarizeCliImportJobs({
-                    jobs,
-                    sourceCount: sources.length,
-                    sourceInputCount: sheetSources.length,
-                    timedOut: false,
-                });
-                context.output.print({
-                    request,
-                    sources,
-                    jobs,
-                    summary,
-                }, (result) => formatQueuedImportOutput({
-                    jobs: result.jobs,
-                    summary: result.summary,
-                    sources: result.sources,
-                }), {
-                    command: 'sheet import',
-                });
-                return;
-            }
-            const waitTimeoutMs = normalizeWaitTimeoutMs(argv.timeoutMs);
-            const waitResult = await waitForCliJobs({
-                getUserJob: async (jobId) => await apiClient.getUserJob(jobId),
-                jobIds: importResult.jobs.map((job) => job.jobId),
-                now: context.now,
-                sleep: context.sleep,
-                timeoutMs: waitTimeoutMs,
-            });
-            const waitedJobsById = new Map(waitResult.jobs.map((job) => [job.id, job]));
-            const jobs = buildSheetImportJobs({
-                importResultJobs: importResult.jobs,
-                sources,
-                waitedJobsById,
-            });
-            const summary = summarizeCliImportJobs({
-                jobs,
-                sourceCount: sources.length,
-                sourceInputCount: sheetSources.length,
-                timedOut: waitResult.timedOut,
-            });
-            const waitError = getWaitError(waitResult);
-            context.output.print({
-                request: {
-                    ...request,
-                    timeoutMs: waitTimeoutMs,
-                },
-                sources,
-                jobs,
-                summary,
-            }, (result) => formatWaitedImportOutput({
-                jobs: result.jobs,
-                summary: result.summary,
-            }), {
-                command: 'sheet import',
-                ok: waitError == null,
-                error: waitError,
-            });
-            throwSilentExitCode(getWaitExitCode(waitResult));
-        }
-        finally {
-            await cleanupResolvedSources(resolvedSources);
-        }
-    })
-        .command('import-solutions [exerciseSheetId] [sources..]', 'Import one or more solution files into an existing exercise sheet', (importSolutionsYargs) => importSolutionsYargs
-        .positional('exerciseSheetId', {
-        type: 'string',
-        describe: 'Exercise sheet ID to reconcile imported solutions into',
-    })
-        .positional('sources', {
-        array: true,
-        type: 'string',
-        describe: 'Local file paths, directories, or HTTP(S) URLs',
-    })
-        .option('manifest', {
-        type: 'string',
-        describe: 'Load sources from a manifest file, or "-" for stdin',
-    })
-        .option('relative-path', {
-        type: 'string',
-        describe: 'Override the relative path for a single positional source',
-    })
-        .option('timeout-ms', {
-        type: 'number',
-        default: 300000,
-        describe: 'Maximum time to wait before timing out',
-    })
-        .option('wait', {
-        type: 'boolean',
-        default: false,
-        describe: 'Wait for the queued job to finish',
-    })
-        .example('chalksurf sheet import-solutions 00000000-0000-4000-8000-000000000001 ./fixtures/solutions.pdf --wait', 'Attach a separate solution file to an existing exercise sheet')
-        .example('cat sheet-solution-import.json | chalksurf --profile prod-codex sheet import-solutions --manifest - --wait --json', 'Drive sheet solution imports from a manifest in an agent or CI flow')
-        .epilogue('When --wait is set, the command exits after the queued import job reaches a terminal state.'), async (argv) => {
-        const config = await context.configStore.loadProfile({ profileName: argv.profile });
-        const rawSources = (argv.sources ?? []).map(String);
-        const manifestPath = argv.manifest === '' ? '-' : argv.manifest;
-        const normalizedRawSources = manifestPath === '-' && rawSources[0] === '-' ? rawSources.slice(1) : rawSources;
-        const resolvedBaseUrl = requireResolvedBaseUrl({
-            flagValue: argv.baseUrl,
-            env: context.env,
-            config,
-        });
-        const resolvedToken = requireResolvedToken({
-            env: context.env,
-            config,
-        });
-        const commandSources = await buildFileImportCommandSources({
-            cwd: context.cwd,
-            loadManifest: loadExerciseSheetSolutionImportManifest,
-            manifestPath,
-            rawSources: normalizedRawSources,
-            relativePath: argv.relativePath,
-            stdin: context.stdin,
-            wait: argv.wait,
-        });
-        const organizationId = resolveRequestedOrganizationId({
-            flagValue: argv.organization,
-            fallbackValue: commandSources.organizationId,
-            env: context.env,
-            config,
-        });
-        const exerciseSheetId = resolveRequestedUuid({
-            flagValue: argv.exerciseSheetId,
-            fallbackValue: commandSources.exerciseSheetId,
-            label: 'exerciseSheetId',
-            required: true,
-        });
-        const apiClient = createApiClient({
-            baseUrl: resolvedBaseUrl.value,
-            token: resolvedToken.value,
-            organizationId,
-        });
-        let resolvedSources = [];
-        try {
-            resolvedSources = await resolveSources({
-                cwd: context.cwd,
-                sources: commandSources.sources,
-            });
-            const sources = buildCliImportSources({
-                resolvedSources,
-            });
-            const formData = await buildFileImportFormData(resolvedSources);
-            formData.set('exerciseSheetId', exerciseSheetId);
-            const request = buildSheetSolutionImportRequest({
-                exerciseSheetId,
-                inputMode: manifestPath ? 'manifest' : 'arguments',
-                organizationId: organizationId ?? null,
-                timeoutMs: commandSources.wait ? normalizeWaitTimeoutMs(argv.timeoutMs) : null,
-                wait: commandSources.wait,
-            });
-            let importResult;
-            try {
-                importResult = await apiClient.importExerciseSheetSolutions(formData);
-            }
-            catch (error) {
-                throw mapApiErrorToCliError(error);
-            }
-            if (!commandSources.wait) {
-                const jobs = [
-                    buildQueuedSheetSolutionImportJob({
-                        jobId: importResult.jobId,
-                        sources,
-                    }),
-                ];
-                const summary = summarizeCliImportJobs({
-                    jobs,
-                    sourceCount: sources.length,
-                    sourceInputCount: commandSources.sources.length,
-                    timedOut: false,
-                });
-                context.output.print({
-                    request,
-                    sources,
-                    jobs,
-                    summary,
-                }, (result) => formatQueuedSheetSolutionImportOutput(result.jobs[0]), {
-                    command: 'sheet import-solutions',
-                });
-                return;
-            }
-            const waitTimeoutMs = normalizeWaitTimeoutMs(argv.timeoutMs);
-            const waitResult = await waitForCliJobs({
-                getUserJob: async (jobId) => await apiClient.getUserJob(jobId),
-                jobIds: [importResult.jobId],
-                now: context.now,
-                sleep: context.sleep,
-                timeoutMs: waitTimeoutMs,
-            });
-            const waitedJob = waitResult.jobs[0];
-            const jobs = [
-                buildWaitedSheetSolutionImportJob({
-                    jobId: importResult.jobId,
-                    sources,
-                    waitedJob: waitedJob == null
-                        ? undefined
-                        : {
-                            ...waitedJob,
-                            id: waitedJob.id,
-                            status: waitedJob.status,
-                        },
-                }),
-            ];
-            const summary = summarizeCliImportJobs({
-                jobs,
-                sourceCount: sources.length,
-                sourceInputCount: commandSources.sources.length,
-                timedOut: waitResult.timedOut,
-            });
-            const waitError = getWaitError({
-                jobs: waitResult.jobs,
-                timedOut: waitResult.timedOut,
-            });
-            context.output.print({
-                request: {
-                    ...request,
-                    timeoutMs: waitTimeoutMs,
-                },
-                sources,
-                jobs,
-                summary,
-            }, (result) => formatWaitedSheetSolutionImportOutput(result.jobs[0]), {
-                command: 'sheet import-solutions',
-                ok: waitError == null,
-                error: waitError,
-            });
-            throwSilentExitCode(getWaitExitCode({ jobs: waitResult.jobs, timedOut: waitResult.timedOut }));
-        }
-        finally {
-            await cleanupResolvedSources(resolvedSources);
-        }
-    })
-        .demandCommand(1)
-        .strict();
-};