@chalksurf/cli 0.2.1 → 0.2.3

package/README.md

@@ -1,21 +1,19 @@
 # `@chalksurf/cli`
 
-Publishable ChalkSurf CLI package.
-
-Current internal release line: `0.2.1`. Expect breaking changes while the CLI is still only used internally.
+Publishable ChalkSurf CLI package. Expect breaking changes while the CLI is still only used internally.
 
 ## Installation
 
 Run the published CLI without a global install:
 
 ```bash
-npx @chalksurf/cli@0.2.1 --help
+npx @chalksurf/cli@ --help
 ```
 
 Install it globally when you want a persistent local binary:
 
 ```bash
-npm install -g @chalksurf/cli@0.2.1
+npm install -g @chalksurf/cli
 chalksurf --version
 ```
 
@@ -34,32 +32,33 @@ Headless or agent flow:
 
 ```bash
 CHALKSURF_TOKEN=cs_cli_... \
-printf '%s' "$CHALKSURF_TOKEN" | npx @chalksurf/cli@0.2.1 auth login \
+printf '%s' "$CHALKSURF_TOKEN" | npx @chalksurf/cli auth login \
   --profile prod-codex \
   --base-url https://chalksurf-api.fly.dev \
   --with-token
 
-npx @chalksurf/cli@0.2.1 --profile prod-codex sheet import --manifest - --wait --json < import.json
+npx @chalksurf/cli --profile prod-codex sheet import --manifest - --wait --json < import.json
 ```
 
-Sheet import manifests use top-level `sheets[]`, where each sheet has one `targetFolderPath` and one or more ordered `sources[]`. See [the canonical example](./docs/examples/sheet-import-manifest.json).
+Sheet import manifests use top-level `sheets[]`, where each sheet has one `targetFolderPath` and one or more ordered `sources[]`. See [the canonical example](./packages/cli/docs/examples/sheet-import-manifest.json).
 
 ## Docs
 
-- [Manual operator guide](./docs/manual.md)
-- [Agent and Codex guide](./docs/agents.md)
-- [Manifest reference](./docs/manifest.md)
-- [Exit codes and JSON errors](./docs/exit-codes.md)
-- [Sheet import schema](./schemas/sheet-import-manifest.schema.json)
-- [Exercise import schema](./schemas/exercise-import-manifest.schema.json)
-- [Exercise solution import schema](./schemas/exercise-solution-import-manifest.schema.json)
+- [Manual operator guide](./packages/cli/docs/manual.md)
+- [Agent and Codex guide](./packages/cli/docs/agents.md)
+- [Manifest reference](./packages/cli/docs/manifest.md)
+- [Exit codes and JSON errors](./packages/cli/docs/exit-codes.md)
+- [Sheet import schema](./packages/cli/schemas/sheet-import-manifest.schema.json)
+- [Exercise import schema](./packages/cli/schemas/exercise-import-manifest.schema.json)
+- [Exercise solution import schema](./packages/cli/schemas/exercise-solution-import-manifest.schema.json)
+- [Exercise sheet solution import schema](./packages/cli/schemas/exercise-sheet-solution-import-manifest.schema.json)
 
 ## Local And Staging Testing
 
 Use separate profiles so local, staging, production, human, and agent tokens do not overwrite each other:
 
 ```bash
-npm run cli-dev -- auth login --profile dev-cztamas --base-url http://localhost:8080
+npm run cli-dev -- auth login --profile dev-cztamas --base-url http://localhost:3101
 npm run cli-dev -- profile use dev-cztamas
 npm run cli-dev -- auth status --json
 npm run cli-dev -- sheet import ./fixtures/algebra.pdf --wait --json

package/dist/bin/chalksurf.js

@@ -14,7 +14,8 @@ import { createConfigStore } from '../lib/config-store.js';
 import { createOutput } from '../lib/output.js';
 import { createPromptSecret } from '../lib/prompt-secret.js';
 const packageJson = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
-const createCli = ({ cwd, configPath, env, now, output, sleep, stdin, promptSecret, }) => {
+const createCli = ({ cwd, configPath, env, now, output, sleep, stdin, }) => {
+    const promptSecret = createPromptSecret();
     const commandContext = {
         cwd,
         configStore: createConfigStore({ configPath, env }),
@@ -101,7 +102,7 @@ const resolveCommandName = (argv) => {
     }
     return 'chalksurf';
 };
-export const runCli = async ({ argv, cwd = process.cwd(), configPath, env = process.env, nowImpl = Date.now, promptSecretImpl = createPromptSecret(), sleepImpl = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)), stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, }) => {
+export const runCli = async ({ argv, cwd = process.cwd(), configPath, env = process.env, nowImpl = Date.now, sleepImpl = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)), stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, }) => {
     const output = createOutput({
         json: hasFlag(argv, ['--json']),
         stdout,
@@ -114,7 +115,6 @@ export const runCli = async ({ argv, cwd = process.cwd(), configPath, env = proc
         env,
         now: nowImpl,
         output,
-        promptSecret: promptSecretImpl,
         sleep: sleepImpl,
         stdin,
     });

package/dist/commands/exercise.js

@@ -1,12 +1,39 @@
 import { z } from 'zod';
 import { createApiClient } from '../lib/api-client.js';
 import { CliCommandError } from '../lib/cli-error.js';
+import { normalizeChoiceValues, normalizeLimit, normalizeOffset, normalizeOptionalInteger, normalizeOptionalText, normalizeOwnership, normalizeStringValues, toApiOwnership, } from '../lib/command-options.js';
 import { buildFileImportCommandSources, buildFileImportFormData, normalizeWaitTimeoutMs } from '../lib/import-files.js';
-import { buildCliImportSources, summarizeCliImportJobs, } from '../lib/import-output.js';
+import { buildCliImportSources, formatCliImportTranslationJobs, summarizeCliImportJobs, } from '../lib/import-output.js';
 import { loadExerciseImportManifest, loadExerciseSolutionImportManifest } from '../lib/manifest.js';
-import { mapApiErrorToCliError, requireResolvedBaseUrl, requireResolvedToken, resolveRequestedOrganizationId, } from '../lib/session.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 { getWaitError, getWaitExitCode, throwSilentExitCode, waitForCliJobs } from '../lib/user-jobs.js';
+const exerciseStatusOptions = ['verified', 'unverified', 'invalid'];
+const getExerciseTextPreview = ({ exercise, language }) => {
+    if (language && exercise.text[language]) {
+        return exercise.text[language];
+    }
+    return Object.values(exercise.text)[0] ?? '';
+};
+const formatExerciseSearchOutput = ({ exercises, language, totalCount, }) => {
+    if (exercises.length === 0) {
+        return 'No exercises found.';
+    }
+    return [
+        `${exercises.length} of ${totalCount} exercise${totalCount === 1 ? '' : 's'} returned.`,
+        ...exercises.map((exercise) => {
+            const preview = getExerciseTextPreview({ exercise, language }).replace(/\s+/g, ' ').trim();
+            const labels = exercise.labels.length > 0 ? ` [${exercise.labels.join(', ')}]` : '';
+            return `${exercise.id}  ${exercise.status}${labels}${preview ? `  ${preview}` : ''}`;
+        }),
+    ].join('\n');
+};
+const normalizeSearchNumberRange = ({ maxDifficulty, minDifficulty, }) => {
+    if (minDifficulty !== null && maxDifficulty !== null && minDifficulty > maxDifficulty) {
+        throw new CliCommandError('--min-difficulty cannot be greater than --max-difficulty.', 2);
+    }
+};
 const resolveRequestedUuid = ({ flagValue, fallbackValue, label, required = false, }) => {
     const resolvedValue = flagValue?.trim() || fallbackValue?.trim();
     if (!resolvedValue) {
@@ -50,6 +77,7 @@ const buildWaitedExerciseImportJob = ({ jobId, sources, waitedJob, }) => {
         error: waitedJob?.error,
         exerciseId: waitedJob?.exerciseId,
         exerciseIds: waitedJob?.exerciseIds,
+        translationJobs: waitedJob?.translationJobs,
     };
 };
 const formatQueuedImportOutput = (job) => {
@@ -66,13 +94,17 @@ const formatQueuedSolutionImportOutput = (job) => {
 };
 const formatWaitedImportOutput = (job) => {
     if (job.status === 'completed') {
+        const translationJobLines = formatCliImportTranslationJobs(job.translationJobs);
         if (job.exerciseIds && job.exerciseIds.length > 0) {
-            return `${job.jobId} completed -> ${job.exerciseIds.length} exercise${job.exerciseIds.length === 1 ? '' : 's'}`;
+            return [
+                `${job.jobId} completed -> ${job.exerciseIds.length} exercise${job.exerciseIds.length === 1 ? '' : 's'}`,
+                ...translationJobLines,
+            ].join('\n');
         }
         if (job.exerciseId) {
-            return `${job.jobId} completed -> ${job.exerciseId}`;
+            return [`${job.jobId} completed -> ${job.exerciseId}`, ...translationJobLines].join('\n');
         }
-        return `${job.jobId} completed`;
+        return [`${job.jobId} completed`, ...translationJobLines].join('\n');
     }
     if (job.status === 'failed') {
         return `${job.jobId} failed -> ${job.error ?? 'Unknown error'}`;
@@ -81,6 +113,133 @@ const formatWaitedImportOutput = (job) => {
 };
 export const registerExerciseCommands = (exerciseYargs, context) => {
     return exerciseYargs
+        .command('search', 'Search exercises visible to the selected organization', (searchYargs) => searchYargs
+        .option('text', {
+        type: 'string',
+        describe: 'Search exercise text. Requires --language.',
+    })
+        .option('language', {
+        type: 'string',
+        describe: 'Language to search or preview, such as english or hungarian',
+    })
+        .option('semantic', {
+        type: 'string',
+        describe: 'Run semantic search with this query text',
+    })
+        .option('label', {
+        array: true,
+        type: 'string',
+        describe: 'Require an exercise label or label prefix',
+    })
+        .option('age', {
+        type: 'number',
+        describe: 'Filter exercises appropriate for this age',
+    })
+        .option('min-difficulty', {
+        type: 'number',
+        describe: 'Minimum difficulty',
+    })
+        .option('max-difficulty', {
+        type: 'number',
+        describe: 'Maximum difficulty',
+    })
+        .option('status', {
+        array: true,
+        type: 'string',
+        describe: `Only include exercises with these statuses (${exerciseStatusOptions.join(', ')})`,
+    })
+        .option('ownership', {
+        type: 'string',
+        default: 'own',
+        describe: 'Visibility scope: own, public, or all',
+    })
+        .option('limit', {
+        type: 'number',
+        default: 20,
+        describe: 'Maximum number of exercises to return',
+    })
+        .option('offset', {
+        type: 'number',
+        default: 0,
+        describe: 'Number of matching exercises to skip',
+    })
+        .example('chalksurf exercise search --text "binomial theorem" --language english --ownership own --json', 'Verify imported exercises in the selected organization')
+        .example('chalksurf --profile prod-codex exercise search --label geometry.triangles --status unverified --json', 'Find agent-created exercises that still need review'), async (argv) => {
+        const text = normalizeOptionalText(argv.text);
+        const language = normalizeOptionalText(argv.language);
+        const semanticSearch = normalizeOptionalText(argv.semantic);
+        const ownership = normalizeOwnership(argv.ownership);
+        const labels = normalizeStringValues(argv.label);
+        const status = normalizeChoiceValues({
+            allowedValues: exerciseStatusOptions,
+            label: '--status',
+            values: argv.status,
+        });
+        const age = normalizeOptionalInteger({ label: '--age', value: argv.age });
+        const minDifficulty = normalizeOptionalInteger({
+            label: '--min-difficulty',
+            value: argv.minDifficulty,
+        });
+        const maxDifficulty = normalizeOptionalInteger({
+            label: '--max-difficulty',
+            value: argv.maxDifficulty,
+        });
+        normalizeSearchNumberRange({ minDifficulty, maxDifficulty });
+        if (text !== null && language === null) {
+            throw new CliCommandError('--language is required when --text is provided.', 2);
+        }
+        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.searchExercises({
+                age,
+                language,
+                labels,
+                minDifficulty,
+                maxDifficulty,
+                text,
+                semanticSearch,
+                status,
+                ownership: toApiOwnership(ownership),
+                limit,
+                offset,
+            });
+        }
+        catch (error) {
+            throw mapApiErrorToCliError(error);
+        }
+        context.output.print({
+            request: {
+                age,
+                language,
+                labels,
+                minDifficulty,
+                maxDifficulty,
+                text,
+                semanticSearch,
+                status: status ?? [],
+                ownership,
+                limit,
+                offset,
+                organizationId: organizationId ?? null,
+            },
+            exercises: searchResult.exercises,
+            totalCount: searchResult.totalCount,
+        }, (result) => formatExerciseSearchOutput({
+            exercises: result.exercises,
+            language: result.request.language ?? undefined,
+            totalCount: result.totalCount,
+        }), {
+            command: 'exercise search',
+        });
+    })
         .command('import [sources..]', 'Import one or more exercises', (importYargs) => importYargs
         .positional('sources', {
         array: true,
@@ -103,6 +262,11 @@ export const registerExerciseCommands = (exerciseYargs, context) => {
         type: 'number',
         default: 300000,
         describe: 'Maximum time to wait before timing out',
+    })
+        .option('translate-to', {
+        array: true,
+        type: 'string',
+        describe: `Generate translated exercise content for these languages (${translationLanguages.join(', ')})`,
     })
         .option('wait', {
         type: 'boolean',
@@ -111,11 +275,15 @@ export const registerExerciseCommands = (exerciseYargs, context) => {
     })
         .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 --profile prod-codex 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) => {
+        .epilogue([
+        'When --wait is set, the command exits after the queued import job reaches a terminal state.',
+        'For translated exercise 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 requestedTranslateTo = resolveRequestedTranslateToLanguages(argv.translateTo);
         const resolvedBaseUrl = requireResolvedBaseUrl({
             flagValue: argv.baseUrl,
             env: context.env,
@@ -145,6 +313,7 @@ export const registerExerciseCommands = (exerciseYargs, context) => {
             fallbackValue: commandSources.exerciseSheetId,
             label: '--sheet-id',
         });
+        const translateToLanguages = requestedTranslateTo ?? commandSources.translateTo;
         const apiClient = createApiClient({
             baseUrl: resolvedBaseUrl.value,
             token: resolvedToken.value,
@@ -170,6 +339,9 @@ export const registerExerciseCommands = (exerciseYargs, context) => {
             if (exerciseSheetId) {
                 formData.set('exerciseSheetId', exerciseSheetId);
             }
+            if (translateToLanguages && translateToLanguages.length > 0) {
+                formData.set('translateToLanguages', JSON.stringify(translateToLanguages));
+            }
             let importResult;
             try {
                 importResult = await apiClient.importExercise(formData);

package/dist/commands/job.js

@@ -1,7 +1,16 @@
-import { createApiClient } from '../lib/api-client.js';
 import { CliCommandError } from '../lib/cli-error.js';
-import { mapApiErrorToCliError, requireResolvedBaseUrl, requireResolvedToken, resolveRequestedOrganizationId, } from '../lib/session.js';
+import { normalizeChoiceValues, normalizeLimit, normalizeOffset, normalizeOptionalText, } from '../lib/command-options.js';
+import { createResolvedApiClient, mapApiErrorToCliError } from '../lib/session.js';
 import { formatCliJobSummary, getWaitError, getWaitExitCode, serializeCliJob, throwSilentExitCode, waitForCliJobs, } from '../lib/user-jobs.js';
+const jobStatusOptions = ['pending', 'in_progress', 'completed', 'failed'];
+const jobTypeOptions = [
+    'exercise_sheet_import',
+    'exercise_import',
+    'exercise_solution_import',
+    'exercise_solution_generation',
+    'exercise_translation_generation',
+    'exercise_sheet_translation_generation',
+];
 const normalizeTimeoutMs = (timeoutMs) => {
     const normalizedTimeoutMs = timeoutMs ?? 300000;
     if (!Number.isFinite(normalizedTimeoutMs) || normalizedTimeoutMs <= 0) {
@@ -9,8 +18,95 @@ const normalizeTimeoutMs = (timeoutMs) => {
     }
     return normalizedTimeoutMs;
 };
+const formatJobListOutput = ({ jobs }) => {
+    if (jobs.length === 0) {
+        return 'No jobs found.';
+    }
+    return jobs.map((job) => formatCliJobSummary(job)).join('\n');
+};
 export const registerJobCommands = (jobYargs, context) => {
     return jobYargs
+        .command('list', 'List jobs for the current user', (listYargs) => listYargs
+        .option('status', {
+        array: true,
+        type: 'string',
+        describe: `Only include jobs with these statuses (${jobStatusOptions.join(', ')})`,
+    })
+        .option('type', {
+        array: true,
+        type: 'string',
+        describe: `Only include jobs with these types (${jobTypeOptions.join(', ')})`,
+    })
+        .option('include-viewed', {
+        type: 'boolean',
+        default: false,
+        describe: 'Include jobs already marked as viewed',
+    })
+        .option('include-dismissed', {
+        type: 'boolean',
+        default: false,
+        describe: 'Include jobs already dismissed in the UI',
+    })
+        .option('limit', {
+        type: 'number',
+        default: 20,
+        describe: 'Maximum number of jobs to return',
+    })
+        .option('offset', {
+        type: 'number',
+        default: 0,
+        describe: 'Number of matching jobs to skip',
+    })
+        .example('chalksurf job list --status failed --include-dismissed --json', 'Find failed jobs for retry')
+        .example('chalksurf --profile prod-codex job list --type exercise_sheet_import --json', 'Inspect agent imports'), async (argv) => {
+        const statuses = normalizeChoiceValues({
+            allowedValues: jobStatusOptions,
+            label: '--status',
+            values: argv.status,
+        });
+        const types = normalizeChoiceValues({
+            allowedValues: jobTypeOptions,
+            label: '--type',
+            values: argv.type,
+        });
+        const limit = normalizeLimit(argv.limit);
+        const offset = normalizeOffset(argv.offset);
+        const { apiClient } = await createResolvedApiClient({
+            context,
+            baseUrlFlagValue: normalizeOptionalText(argv.baseUrl) ?? undefined,
+            organizationFlagValue: normalizeOptionalText(argv.organization) ?? undefined,
+            profileName: argv.profile,
+        });
+        let jobs;
+        try {
+            jobs = await apiClient.listUserJobs({
+                statuses,
+                types,
+                includeViewed: argv.includeViewed === true,
+                includeDismissed: argv.includeDismissed === true,
+                limit,
+                offset,
+            });
+        }
+        catch (error) {
+            throw mapApiErrorToCliError(error);
+        }
+        const serializedJobs = jobs.map(serializeCliJob);
+        context.output.print({
+            request: {
+                statuses: statuses ?? [],
+                types: types ?? [],
+                includeViewed: argv.includeViewed === true,
+                includeDismissed: argv.includeDismissed === true,
+                limit,
+                offset,
+            },
+            jobs: serializedJobs,
+            count: serializedJobs.length,
+        }, (result) => formatJobListOutput({ jobs: result.jobs }), {
+            command: 'job list',
+        });
+    })
         .command('get <jobId>', 'Fetch a single job', (getYargs) => getYargs
         .positional('jobId', {
         type: 'string',
@@ -18,25 +114,11 @@ export const registerJobCommands = (jobYargs, context) => {
     })
         .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.loadProfile({ profileName: argv.profile });
-        const resolvedBaseUrl = requireResolvedBaseUrl({
-            flagValue: argv.baseUrl,
-            env: context.env,
-            config,
-        });
-        const resolvedToken = requireResolvedToken({
-            env: context.env,
-            config,
-        });
-        const organizationId = resolveRequestedOrganizationId({
-            flagValue: argv.organization,
-            env: context.env,
-            config,
-        });
-        const apiClient = createApiClient({
-            baseUrl: resolvedBaseUrl.value,
-            token: resolvedToken.value,
-            organizationId,
+        const { apiClient } = await createResolvedApiClient({
+            context,
+            baseUrlFlagValue: argv.baseUrl,
+            organizationFlagValue: argv.organization,
+            profileName: argv.profile,
         });
         let job;
         try {
@@ -63,25 +145,11 @@ export const registerJobCommands = (jobYargs, context) => {
     })
         .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.loadProfile({ profileName: argv.profile });
-        const resolvedBaseUrl = requireResolvedBaseUrl({
-            flagValue: argv.baseUrl,
-            env: context.env,
-            config,
-        });
-        const resolvedToken = requireResolvedToken({
-            env: context.env,
-            config,
-        });
-        const organizationId = resolveRequestedOrganizationId({
-            flagValue: argv.organization,
-            env: context.env,
-            config,
-        });
-        const apiClient = createApiClient({
-            baseUrl: resolvedBaseUrl.value,
-            token: resolvedToken.value,
-            organizationId,
+        const { apiClient } = await createResolvedApiClient({
+            context,
+            baseUrlFlagValue: argv.baseUrl,
+            organizationFlagValue: argv.organization,
+            profileName: argv.profile,
         });
         const timeoutMs = normalizeTimeoutMs(argv.timeoutMs);
         const waitResult = await waitForCliJobs({