@chalksurf/cli 0.1.0 → 0.2.0

package/dist/commands/exercise.js

@@ -0,0 +1,428 @@
+import { z } from 'zod';
+import { createApiClient } from '../lib/api-client.js';
+import { CliCommandError } from '../lib/cli-error.js';
+import { buildFileImportCommandSources, buildFileImportFormData, normalizeWaitTimeoutMs } from '../lib/import-files.js';
+import { buildCliImportSources, summarizeCliImportJobs, } from '../lib/import-output.js';
+import { loadExerciseImportManifest, loadExerciseSolutionImportManifest } from '../lib/manifest.js';
+import { mapApiErrorToCliError, requireResolvedBaseUrl, requireResolvedToken, resolveRequestedOrganizationId, } from '../lib/session.js';
+import { cleanupResolvedSources, resolveSources } from '../lib/source-resolver.js';
+import { getWaitError, getWaitExitCode, throwSilentExitCode, waitForCliJobs } from '../lib/user-jobs.js';
+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 buildExerciseImportRequest = ({ exerciseId, exerciseSheetId, inputMode, organizationId, timeoutMs, wait, }) => {
+    return {
+        organizationId,
+        inputMode,
+        wait,
+        timeoutMs,
+        target: {
+            ...(exerciseId === undefined ? {} : { exerciseId }),
+            ...(exerciseSheetId === undefined ? {} : { exerciseSheetId }),
+        },
+    };
+};
+const buildQueuedExerciseImportJob = ({ jobId, sources, }) => {
+    return {
+        jobId,
+        sourceIndexes: sources.map((source) => source.sourceIndex),
+        sourceIds: sources.map((source) => source.sourceId).filter((sourceId) => sourceId !== null),
+        status: 'queued',
+    };
+};
+const buildWaitedExerciseImportJob = ({ 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,
+        exerciseId: waitedJob?.exerciseId,
+        exerciseIds: waitedJob?.exerciseIds,
+    };
+};
+const formatQueuedImportOutput = (job) => {
+    return [
+        'Queued exercise import.',
+        `${job.jobId}  ${job.sourceIndexes.length} source${job.sourceIndexes.length === 1 ? '' : 's'}`,
+    ].join('\n');
+};
+const formatQueuedSolutionImportOutput = (job) => {
+    return [
+        'Queued exercise solution import.',
+        `${job.jobId}  ${job.sourceIndexes.length} source${job.sourceIndexes.length === 1 ? '' : 's'}`,
+    ].join('\n');
+};
+const formatWaitedImportOutput = (job) => {
+    if (job.status === 'completed') {
+        if (job.exerciseIds && job.exerciseIds.length > 0) {
+            return `${job.jobId} completed -> ${job.exerciseIds.length} exercise${job.exerciseIds.length === 1 ? '' : 's'}`;
+        }
+        if (job.exerciseId) {
+            return `${job.jobId} completed -> ${job.exerciseId}`;
+        }
+        return `${job.jobId} completed`;
+    }
+    if (job.status === 'failed') {
+        return `${job.jobId} failed -> ${job.error ?? 'Unknown error'}`;
+    }
+    return `${job.jobId} ${job.status ?? 'pending'}`;
+};
+export const registerExerciseCommands = (exerciseYargs, context) => {
+    return exerciseYargs
+        .command('import [sources..]', 'Import one or more exercises', (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('sheet-id', {
+        type: 'string',
+        describe: 'Append the imported exercises to an existing sheet',
+    })
+        .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 exercise import ./fixtures/problem-set.pdf --sheet-id 00000000-0000-4000-8000-000000000001 --wait', 'Import a problem set into an existing sheet')
+        .example('cat exercise-import.json | chalksurf exercise import --manifest - --wait --json', 'Drive 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.load();
+        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: loadExerciseImportManifest,
+            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.sheetId,
+            fallbackValue: commandSources.exerciseSheetId,
+            label: '--sheet-id',
+        });
+        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);
+            const request = buildExerciseImportRequest({
+                exerciseSheetId: exerciseSheetId ?? null,
+                inputMode: manifestPath ? 'manifest' : 'arguments',
+                organizationId: organizationId ?? null,
+                timeoutMs: commandSources.wait ? normalizeWaitTimeoutMs(argv.timeoutMs) : null,
+                wait: commandSources.wait,
+            });
+            if (exerciseSheetId) {
+                formData.set('exerciseSheetId', exerciseSheetId);
+            }
+            let importResult;
+            try {
+                importResult = await apiClient.importExercise(formData);
+            }
+            catch (error) {
+                throw mapApiErrorToCliError(error);
+            }
+            if (!commandSources.wait) {
+                const jobs = [
+                    buildQueuedExerciseImportJob({
+                        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) => formatQueuedImportOutput(result.jobs[0]), {
+                    command: 'exercise import',
+                });
+                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 = [
+                buildWaitedExerciseImportJob({
+                    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) => formatWaitedImportOutput(result.jobs[0]), {
+                command: 'exercise import',
+                ok: waitError == null,
+                error: waitError,
+            });
+            throwSilentExitCode(getWaitExitCode({ jobs: waitResult.jobs, timedOut: waitResult.timedOut }));
+        }
+        catch (error) {
+            throw error;
+        }
+        finally {
+            await cleanupResolvedSources(resolvedSources);
+        }
+    })
+        .command('import-solution [exerciseId] [sources..]', 'Import one or more exercise solution files', (importSolutionYargs) => importSolutionYargs
+        .positional('exerciseId', {
+        type: 'string',
+        describe: 'Exercise ID to attach the imported solution to',
+    })
+        .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 exercise import-solution 00000000-0000-4000-8000-000000000001 ./fixtures/solution.pdf --wait', 'Attach a solution file to an existing exercise')
+        .example('cat exercise-solution-import.json | chalksurf exercise import-solution --manifest - --wait --json', 'Drive 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.load();
+        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: loadExerciseSolutionImportManifest,
+            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 exerciseId = resolveRequestedUuid({
+            flagValue: argv.exerciseId,
+            fallbackValue: commandSources.exerciseId,
+            label: 'exerciseId',
+            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('exerciseId', exerciseId);
+            const request = buildExerciseImportRequest({
+                exerciseId,
+                inputMode: manifestPath ? 'manifest' : 'arguments',
+                organizationId: organizationId ?? null,
+                timeoutMs: commandSources.wait ? normalizeWaitTimeoutMs(argv.timeoutMs) : null,
+                wait: commandSources.wait,
+            });
+            let importResult;
+            try {
+                importResult = await apiClient.importExerciseSolution(formData);
+            }
+            catch (error) {
+                throw mapApiErrorToCliError(error);
+            }
+            if (!commandSources.wait) {
+                const jobs = [
+                    buildQueuedExerciseImportJob({
+                        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) => formatQueuedSolutionImportOutput(result.jobs[0]), {
+                    command: 'exercise import-solution',
+                });
+                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 = [
+                buildWaitedExerciseImportJob({
+                    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) => formatWaitedImportOutput(result.jobs[0]), {
+                command: 'exercise import-solution',
+                ok: waitError == null,
+                error: waitError,
+            });
+            throwSilentExitCode(getWaitExitCode({ jobs: waitResult.jobs, timedOut: waitResult.timedOut }));
+        }
+        finally {
+            await cleanupResolvedSources(resolvedSources);
+        }
+    })
+        .demandCommand(1)
+        .strict();
+};

package/dist/commands/job.js

@@ -1,7 +1,7 @@
 import { createApiClient } from '../lib/api-client.js';
 import { CliCommandError } from '../lib/cli-error.js';
 import { mapApiErrorToCliError, requireResolvedBaseUrl, requireResolvedToken, resolveRequestedOrganizationId, } from '../lib/session.js';
-import { formatCliJobSummary, getWaitExitCode, serializeCliJob, throwSilentExitCode, waitForCliJobs, } from '../lib/user-jobs.js';
+import { formatCliJobSummary, getWaitError, getWaitExitCode, serializeCliJob, throwSilentExitCode, waitForCliJobs, } from '../lib/user-jobs.js';
 const normalizeTimeoutMs = (timeoutMs) => {
     const normalizedTimeoutMs = timeoutMs ?? 300000;
     if (!Number.isFinite(normalizedTimeoutMs) || normalizedTimeoutMs <= 0) {
@@ -11,10 +11,13 @@ const normalizeTimeoutMs = (timeoutMs) => {
 };
 export const registerJobCommands = (jobYargs, context) => {
     return jobYargs
-        .command('get <jobId>', 'Fetch a single job', (getYargs) => getYargs.positional('jobId', {
+        .command('get <jobId>', 'Fetch a single job', (getYargs) => getYargs
+        .positional('jobId', {
         type: 'string',
         describe: 'Job ID to fetch',
-    }), async (argv) => {
+    })
+        .example('chalksurf job get job_123', 'Read one job in human-readable mode')
+        .example('chalksurf job get job_123 --json', 'Read one job in machine-readable mode'), async (argv) => {
         const config = await context.configStore.load();
         const resolvedBaseUrl = requireResolvedBaseUrl({
             flagValue: argv.baseUrl,
@@ -34,7 +37,6 @@ export const registerJobCommands = (jobYargs, context) => {
             baseUrl: resolvedBaseUrl.value,
             token: resolvedToken.value,
             organizationId,
-            fetchImpl: context.fetchImpl,
         });
         let job;
         try {
@@ -44,7 +46,9 @@ export const registerJobCommands = (jobYargs, context) => {
             throw mapApiErrorToCliError(error);
         }
         const serializedJob = serializeCliJob(job);
-        context.output.print({ job: serializedJob }, (result) => formatCliJobSummary(result.job));
+        context.output.print({ job: serializedJob }, (result) => formatCliJobSummary(result.job), {
+            command: 'job get',
+        });
     })
         .command('wait <jobIds..>', 'Poll jobs until they complete, fail, or time out', (waitYargs) => waitYargs
         .positional('jobIds', {
@@ -56,7 +60,9 @@ export const registerJobCommands = (jobYargs, context) => {
         type: 'number',
         default: 300000,
         describe: 'Maximum time to wait before timing out',
-    }), async (argv) => {
+    })
+        .example('chalksurf job wait job_123 job_124', 'Wait for one or more jobs to reach a terminal state')
+        .example('chalksurf job wait job_123 --timeout-ms 60000 --json', 'Poll a job for up to 60 seconds'), async (argv) => {
         const config = await context.configStore.load();
         const resolvedBaseUrl = requireResolvedBaseUrl({
             flagValue: argv.baseUrl,
@@ -76,7 +82,6 @@ export const registerJobCommands = (jobYargs, context) => {
             baseUrl: resolvedBaseUrl.value,
             token: resolvedToken.value,
             organizationId,
-            fetchImpl: context.fetchImpl,
         });
         const timeoutMs = normalizeTimeoutMs(argv.timeoutMs);
         const waitResult = await waitForCliJobs({
@@ -86,7 +91,12 @@ export const registerJobCommands = (jobYargs, context) => {
             sleep: context.sleep,
             timeoutMs,
         });
-        context.output.print(waitResult, (result) => result.jobs.map((job) => formatCliJobSummary(job)).join('\n'));
+        const waitError = getWaitError(waitResult);
+        context.output.print(waitResult, (result) => result.jobs.map((job) => formatCliJobSummary(job)).join('\n'), {
+            command: 'job wait',
+            ok: waitError == null,
+            error: waitError,
+        });
         throwSilentExitCode(getWaitExitCode(waitResult));
     })
         .demandCommand(1)

package/dist/commands/org.js

@@ -13,7 +13,9 @@ const serializeOrganization = ({ organizationId, organizationName, organizationT
 };
 export const registerOrgCommands = (orgYargs, context) => {
     return orgYargs
-        .command('list', 'List organizations available to the authenticated user', () => { }, async (argv) => {
+        .command('list', 'List organizations available to the authenticated user', (listYargs) => listYargs
+        .example('chalksurf org list', 'List organizations for the current session')
+        .example('chalksurf org list --json', 'Inspect the available organizations in machine-readable mode'), async (argv) => {
         const config = await context.configStore.load();
         const resolvedBaseUrl = requireResolvedBaseUrl({
             flagValue: argv.baseUrl,
@@ -27,7 +29,6 @@ export const registerOrgCommands = (orgYargs, context) => {
         const apiClient = createApiClient({
             baseUrl: resolvedBaseUrl.value,
             token: resolvedToken.value,
-            fetchImpl: context.fetchImpl,
         });
         let profile;
         try {
@@ -53,16 +54,19 @@ export const registerOrgCommands = (orgYargs, context) => {
             organizations,
             selectedOrganizationId: resolvedOrganization.organization?.organizationId ?? null,
             selectedOrganizationSource: resolvedOrganization.source,
-            warnings: resolvedOrganization.warnings,
         }, (result) => result.organizations
             .map((organization) => `${organization.selected ? '*' : ' '} ${organization.name} (${organization.id}) [${organization.type}, ${organization.role}]`)
-            .join('\n'));
+            .join('\n'), {
+            command: 'org list',
+        });
     })
         .command('use <organizationId>', 'Set the default organization used by the CLI', (useYargs) => {
-        return useYargs.positional('organizationId', {
+        return useYargs
+            .positional('organizationId', {
             type: 'string',
             describe: 'Organization ID to store as the default',
-        });
+        })
+            .example('chalksurf org use org_123', 'Store org_123 as the default organization for future commands');
     }, async (argv) => {
         const config = await context.configStore.load();
         const resolvedBaseUrl = requireResolvedBaseUrl({
@@ -77,7 +81,6 @@ export const registerOrgCommands = (orgYargs, context) => {
         const apiClient = createApiClient({
             baseUrl: resolvedBaseUrl.value,
             token: resolvedToken.value,
-            fetchImpl: context.fetchImpl,
         });
         let profile;
         try {
@@ -99,7 +102,9 @@ export const registerOrgCommands = (orgYargs, context) => {
                 ...organization,
                 selected: true,
             }),
-        }, (result) => `Default organization set to ${result.organization.name} (${result.organization.id}).`);
+        }, (result) => `Default organization set to ${result.organization.name} (${result.organization.id}).`, {
+            command: 'org use',
+        });
     })
         .demandCommand(1)
         .strict();