@chalksurf/cli 0.2.0 → 0.2.2

package/dist/commands/sheet.js

@@ -1,11 +1,13 @@
+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, summarizeCliImportJobs, } from '../lib/import-output.js';
-import { loadSheetImportManifest, } from '../lib/manifest.js';
-import { mapApiErrorToCliError, requireResolvedBaseUrl, requireResolvedToken, resolveRequestedOrganizationId, } from '../lib/session.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 { translationLanguages } from '../lib/translation-languages.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 isValidTargetFolderPath = (value) => {
@@ -44,20 +46,6 @@ const normalizeOptionalTitle = (value) => {
     }
     return normalizedValue;
 };
-const resolveRequestedTranslateToLanguages = (rawValues) => {
-    if (!rawValues || rawValues.length === 0) {
-        return undefined;
-    }
-    const invalidLanguage = rawValues.find((value) => !translationLanguages.includes(value));
-    if (invalidLanguage) {
-        throw new CliCommandError(`--translate-to must be one of: ${translationLanguages.join(', ')}`, 2);
-    }
-    const languages = rawValues;
-    if (new Set(languages).size !== languages.length) {
-        throw new CliCommandError('--translate-to languages must be unique.', 2);
-    }
-    return languages;
-};
 const normalizeOptionalTargetFolderPath = (value) => {
     const normalizedValue = value?.trim();
     if (!normalizedValue) {
@@ -65,6 +53,20 @@ const normalizeOptionalTargetFolderPath = (value) => {
     }
     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('\\', '/')
@@ -180,6 +182,7 @@ const buildSheetImportJobs = ({ importResultJobs, sources, waitedJobsById, }) =>
             status: waitedJob?.status ?? 'queued',
             error: waitedJob?.error,
             exerciseSheetId: waitedJob?.exerciseSheetId,
+            translationJobs: waitedJob?.translationJobs,
         };
     });
 };
@@ -192,6 +195,38 @@ const buildSheetImportRequest = ({ inputMode, organizationId, timeoutMs, wait, }
         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'}`;
@@ -211,22 +246,112 @@ const formatQueuedImportOutput = ({ jobs, summary, sources, }) => {
 const formatWaitedImportOutput = ({ jobs, summary, }) => {
     return [
         `${jobs.length} job${jobs.length === 1 ? '' : 's'} queued.`,
-        ...jobs.map((job) => formatCliJobSummary({
-            id: job.jobId,
-            status: job.status === 'queued' ? 'pending' : job.status,
-            type: 'exercise_sheet_import',
-            createdAt: '',
-            updatedAt: '',
-            error: job.error,
-            exerciseSheetId: job.exerciseSheetId,
-        })),
+        ...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,
+            }),
+            ...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,
@@ -271,12 +396,12 @@ export const registerSheetCommands = (sheetYargs, context) => {
     })
         .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 sheet import --manifest - --wait --json', 'Drive multi-source sheet imports from a manifest in an agent or CI flow')
+        .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 only after the full requested import is complete.',
-        'For translated sheet imports, that includes generating and storing the requested translations.',
+        '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.load();
+        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;
@@ -429,6 +554,175 @@ export const registerSheetCommands = (sheetYargs, context) => {
         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();

package/dist/lib/api-client.js

@@ -58,12 +58,18 @@ export const createApiClient = ({ baseUrl, token, organizationId, }) => {
         getUserProfile: async () => {
             return await query('getUserProfile', null);
         },
-        listUserJobs: async () => {
-            return await query('listUserJobs', null);
+        listUserJobs: async (input) => {
+            return await query('listUserJobs', input ?? null);
         },
         getUserJob: async (id) => {
             return await query('getUserJob', { id });
         },
+        searchExercises: async (input) => {
+            return await mutation('searchExercises', input);
+        },
+        searchExerciseSheets: async (input) => {
+            return await mutation('searchExerciseSheets', input);
+        },
         importExerciseSheet: async (formData) => {
             return await mutation('importExerciseSheet', formData);
         },
@@ -73,5 +79,8 @@ export const createApiClient = ({ baseUrl, token, organizationId, }) => {
         importExerciseSolution: async (formData) => {
             return await mutation('importExerciseSolution', formData);
         },
+        importExerciseSheetSolutions: async (formData) => {
+            return await mutation('importExerciseSheetSolutions', formData);
+        },
     };
 };

package/dist/lib/command-options.js

@@ -0,0 +1,61 @@
+import { CliCommandError } from './cli-error.js';
+export const cliDefaultLimit = 20;
+export const cliMaxLimit = 100;
+const normalizeOptionalString = (value) => {
+    const normalizedValue = value?.trim();
+    return normalizedValue ? normalizedValue : undefined;
+};
+export const normalizeOptionalText = (value) => {
+    return normalizeOptionalString(value) ?? null;
+};
+export const normalizeLimit = (value) => {
+    const normalizedValue = value ?? cliDefaultLimit;
+    if (!Number.isInteger(normalizedValue) || normalizedValue < 1 || normalizedValue > cliMaxLimit) {
+        throw new CliCommandError(`--limit must be an integer between 1 and ${cliMaxLimit}.`, 2);
+    }
+    return normalizedValue;
+};
+export const normalizeOffset = (value) => {
+    const normalizedValue = value ?? 0;
+    if (!Number.isInteger(normalizedValue) || normalizedValue < 0) {
+        throw new CliCommandError('--offset must be a non-negative integer.', 2);
+    }
+    return normalizedValue;
+};
+export const normalizeOptionalInteger = ({ label, value }) => {
+    if (value === undefined) {
+        return null;
+    }
+    if (!Number.isInteger(value)) {
+        throw new CliCommandError(`${label} must be an integer.`, 2);
+    }
+    return value;
+};
+export const normalizeChoiceValues = ({ allowedValues, label, values, }) => {
+    if (!values || values.length === 0) {
+        return undefined;
+    }
+    const normalizedValues = values.map((value) => value.trim()).filter((value) => value.length > 0);
+    const invalidValue = normalizedValues.find((value) => !allowedValues.includes(value));
+    if (invalidValue) {
+        throw new CliCommandError(`${label} must be one of: ${allowedValues.join(', ')}`, 2);
+    }
+    return Array.from(new Set(normalizedValues));
+};
+export const normalizeStringValues = (values) => {
+    if (!values || values.length === 0) {
+        return [];
+    }
+    return Array.from(new Set(values.map((value) => value.trim()).filter((value) => value.length > 0)));
+};
+export const ownershipOptions = ['own', 'public', 'all'];
+export const normalizeOwnership = (value) => {
+    const normalizedValue = normalizeOptionalString(value) ?? 'own';
+    if (!ownershipOptions.includes(normalizedValue)) {
+        throw new CliCommandError(`--ownership must be one of: ${ownershipOptions.join(', ')}`, 2);
+    }
+    return normalizedValue;
+};
+export const toApiOwnership = (ownership) => {
+    return ownership === 'all' ? null : ownership;
+};