@chalksurf/cli 0.3.0 → 0.3.1

package/dist/bin/chalksurf.js

@@ -132,6 +132,12 @@ var createApiClient = ({
     agentSetExerciseVisibility: async (input) => {
       return await mutation("agentSetExerciseVisibility", input);
     },
+    agentStartExerciseTranslationGeneration: async (input) => {
+      return await mutation(
+        "agentStartExerciseTranslationGeneration",
+        input
+      );
+    },
     agentGetSheet: async (id) => {
       return await query("agentGetSheet", { id });
     },
@@ -159,6 +165,12 @@ var createApiClient = ({
     agentSetSheetVisibility: async (input) => {
       return await mutation("agentSetSheetVisibility", input);
     },
+    agentStartSheetTranslationGeneration: async (input) => {
+      return await mutation(
+        "agentStartSheetTranslationGeneration",
+        input
+      );
+    },
     agentAppendExercisesToSheet: async (input) => {
       return await mutation("agentAppendExercisesToSheet", input);
     },
@@ -1448,7 +1460,11 @@ var Constants = {
         "import_sheet_started",
         "import_sheet_completed",
         "import_sheet_solutions_started",
-        "import_sheet_solutions_completed"
+        "import_sheet_solutions_completed",
+        "generate_exercise_translation_started",
+        "generate_exercise_translation_completed",
+        "generate_sheet_translation_started",
+        "generate_sheet_translation_completed"
       ],
       agent_audit_outcome: ["started", "success", "failed", "denied"],
       agent_audit_resource_type: ["exercise", "sheet", "folder", "job", "event"],
@@ -1680,6 +1696,28 @@ var agentWriteOperationRegistry = {
     receiptOperation: null,
     resourceType: "sheet",
     sync: false
+  },
+  generate_exercise_translation_started: {
+    agentToolName: "start_exercise_translation_generation",
+    receiptOperation: null,
+    resourceType: "job",
+    sync: false
+  },
+  generate_exercise_translation_completed: {
+    receiptOperation: null,
+    resourceType: "exercise",
+    sync: false
+  },
+  generate_sheet_translation_started: {
+    agentToolName: "start_sheet_translation_generation",
+    receiptOperation: null,
+    resourceType: "job",
+    sync: false
+  },
+  generate_sheet_translation_completed: {
+    receiptOperation: null,
+    resourceType: "sheet",
+    sync: false
   }
 };
 var agentWriteReceiptOperations = Object.values(agentWriteOperationRegistry).map((operation) => operation.receiptOperation).filter((operation) => Boolean(operation));
@@ -1979,6 +2017,40 @@ var validateLatexSnippetsAgentInputSchema = strictObject({
 var validateLatexSnippetsAgentOutputSchema = strictObject({
   results: z.array(latexValidationResultSchema)
 });
+var queuedExerciseTranslationJobSchema = strictObject({
+  exerciseId: uuidSchema,
+  jobId: uuidSchema,
+  languages: z.array(z.enum(translationLanguages)).min(1),
+  type: z.literal("exercise_translation_generation")
+});
+var queuedSheetTranslationJobSchema = strictObject({
+  exerciseSheetId: uuidSchema,
+  jobId: uuidSchema,
+  language: z.enum(translationLanguages),
+  type: z.literal("exercise_sheet_translation_generation")
+});
+var skippedSheetTranslationJobSchema = strictObject({
+  jobId: z.null(),
+  language: z.enum(translationLanguages),
+  reason: z.literal("already_complete"),
+  type: z.literal("exercise_sheet_translation_generation")
+});
+var targetTranslationLanguagesSchema = z.array(z.enum(translationLanguages)).min(1).refine((languages) => new Set(languages).size === languages.length, "Target languages must be unique");
+var startExerciseTranslationGenerationAgentInputSchema = strictObject({
+  id: uuidSchema,
+  targetLanguages: targetTranslationLanguagesSchema
+});
+var startExerciseTranslationGenerationAgentOutputSchema = strictObject({
+  jobs: z.array(queuedExerciseTranslationJobSchema)
+});
+var startSheetTranslationGenerationAgentInputSchema = strictObject({
+  id: uuidSchema,
+  sourceLanguage: z.enum(translationLanguages).optional(),
+  targetLanguages: targetTranslationLanguagesSchema
+});
+var startSheetTranslationGenerationAgentOutputSchema = strictObject({
+  jobs: z.array(z.union([queuedSheetTranslationJobSchema, skippedSheetTranslationJobSchema]))
+});
 var sendUserFeedbackAgentInputSchema = strictObject({
   message: feedbackMessageSchema,
   userConsent: z.literal(true),
@@ -2415,6 +2487,10 @@ var setExerciseVisibilityInputSchema = setExerciseVisibilityAgentInputSchema.ext
   organizationId: organizationIdSchema
 });
 var setExerciseVisibilityOutputSchema = setExerciseVisibilityAgentOutputSchema;
+var generateExerciseTranslationJobInputSchema = startExerciseTranslationGenerationAgentInputSchema.extend({
+  organizationId: organizationIdSchema
+});
+var generateExerciseTranslationJobOutputSchema = startExerciseTranslationGenerationAgentOutputSchema;
 var importExerciseInputSchema = strictObject2({
   organizationId: organizationIdSchema,
   sources: importSourcesSchema,
@@ -2485,6 +2561,10 @@ var setSheetVisibilityInputSchema = setSheetVisibilityAgentInputSchema.extend({
   organizationId: organizationIdSchema
 });
 var setSheetVisibilityOutputSchema = setSheetVisibilityAgentOutputSchema;
+var generateSheetTranslationJobInputSchema = startSheetTranslationGenerationAgentInputSchema.extend({
+  organizationId: organizationIdSchema
+});
+var generateSheetTranslationJobOutputSchema = startSheetTranslationGenerationAgentOutputSchema;
 var appendExercisesToSheetInputSchema = appendExercisesToSheetAgentInputSchema.extend({
   organizationId: organizationIdSchema
 });
@@ -2676,6 +2756,16 @@ var chalksurfMcpToolCapabilities = {
     requiredPermission: "write",
     security: { type: "oauth2", scopes: [chalksurfMcpScopes.write] }
   },
+  generate_exercise_translation_job: {
+    name: "generate_exercise_translation_job",
+    title: "Generate exercise translation job",
+    description: "Use this to queue translation generation for one writable ChalkSurf exercise.",
+    inputSchema: generateExerciseTranslationJobInputSchema,
+    outputSchema: generateExerciseTranslationJobOutputSchema,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    requiredPermission: "write",
+    security: { type: "oauth2", scopes: [chalksurfMcpScopes.write] }
+  },
   import_exercise: {
     name: "import_exercise",
     title: "Import exercise",
@@ -2796,6 +2886,16 @@ var chalksurfMcpToolCapabilities = {
     requiredPermission: "write",
     security: { type: "oauth2", scopes: [chalksurfMcpScopes.write] }
   },
+  generate_sheet_translation_job: {
+    name: "generate_sheet_translation_job",
+    title: "Generate sheet translation job",
+    description: "Use this to queue translation generation for one writable ChalkSurf exercise sheet.",
+    inputSchema: generateSheetTranslationJobInputSchema,
+    outputSchema: generateSheetTranslationJobOutputSchema,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    requiredPermission: "write",
+    security: { type: "oauth2", scopes: [chalksurfMcpScopes.write] }
+  },
   append_exercises_to_sheet: {
     name: "append_exercises_to_sheet",
     title: "Append exercises to sheet",
@@ -5053,6 +5153,13 @@ var formatUpdateExerciseOutput = ({ receipt }) => {
 var formatSetExerciseVisibilityOutput = ({ receipt }) => {
   return formatAgentWriteReceiptOutput({ receipt });
 };
+var getExerciseTranslationJobIds = ({ jobs }) => jobs.map((job) => job.jobId);
+var formatExerciseTranslationOutput = ({ jobs }) => {
+  if (jobs.length === 0) {
+    return "No exercise translation jobs queued.";
+  }
+  return jobs.map((job) => `${job.jobId}  exercise ${job.exerciseId}  ${job.languages.join(", ")}`).join("\n");
+};
 var resolveVisibilityFlag = ({ privateFlag, publicFlag }) => {
   if (publicFlag && privateFlag) {
     throw new CliCommandError("--public and --private cannot be used together.", 2);
@@ -5719,6 +5826,98 @@ var registerExerciseCommands = (exerciseYargs, context) => {
         }
       );
     }
+  ).command(
+    "translate [exerciseId]",
+    "Queue translation generation for an existing exercise",
+    (translateYargs) => translateYargs.positional("exerciseId", {
+      type: "string",
+      describe: "Exercise ID to translate"
+    }).option("translate-to", {
+      array: true,
+      type: "string",
+      describe: `Generate translated exercise content for these languages (${translationLanguages2.join(", ")})`
+    }).option("timeout-ms", {
+      type: "number",
+      default: 3e5,
+      describe: "Maximum time to wait before timing out"
+    }).option("wait", {
+      type: "boolean",
+      default: false,
+      describe: "Wait for the queued translation job to finish"
+    }).example(
+      "chalksurf exercise translate 00000000-0000-4000-8000-000000000001 --translate-to english --json",
+      "Queue exercise translation generation"
+    ),
+    async (argv) => {
+      const id = resolveRequestedUuid({
+        fallbackValue: argv.exerciseId,
+        label: "exerciseId",
+        required: true
+      });
+      const targetLanguages = resolveRequestedTranslateToLanguages(argv.translateTo);
+      if (!targetLanguages || targetLanguages.length === 0) {
+        throw new CliCommandError("--translate-to is required at least once.", 2);
+      }
+      const input = { id, targetLanguages };
+      const { apiClient, organizationId } = await createResolvedApiClient({
+        context,
+        baseUrlFlagValue: argv.baseUrl,
+        organizationFlagValue: argv.organization,
+        profileName: argv.profile
+      });
+      let result;
+      try {
+        result = await apiClient.agentStartExerciseTranslationGeneration(input);
+      } catch (error) {
+        throw mapApiErrorToCliError(error);
+      }
+      if (argv.wait !== true) {
+        context.output.print(
+          {
+            request: {
+              ...input,
+              organizationId: organizationId ?? null,
+              wait: false,
+              timeoutMs: null
+            },
+            jobs: result.jobs
+          },
+          (output) => formatExerciseTranslationOutput({ jobs: output.jobs }),
+          {
+            command: "exercise translate"
+          }
+        );
+        return;
+      }
+      const timeoutMs = normalizeWaitTimeoutMs(argv.timeoutMs);
+      const waitResult = await waitForCliJobs({
+        getUserJob: async (jobId) => await apiClient.getUserJob(jobId),
+        jobIds: getExerciseTranslationJobIds(result),
+        now: context.now,
+        sleep: context.sleep,
+        timeoutMs
+      });
+      const waitError = getWaitError(waitResult);
+      context.output.print(
+        {
+          request: {
+            ...input,
+            organizationId: organizationId ?? null,
+            wait: true,
+            timeoutMs
+          },
+          jobs: result.jobs,
+          wait: waitResult
+        },
+        (output) => output.wait.jobs.map((job) => formatCliJobSummary(job)).join("\n"),
+        {
+          command: "exercise translate",
+          ok: waitError == null,
+          error: waitError
+        }
+      );
+      throwSilentExitCode(getWaitExitCode(waitResult));
+    }
   ).command(
     "validate-latex",
     "Validate LaTeX snippets before updating exercise or sheet content",
@@ -7194,6 +7393,15 @@ var formatUpdateSheetOutput = ({ receipt }) => {
 var formatSetSheetVisibilityOutput = ({ receipt }) => {
   return formatAgentWriteReceiptOutput({ receipt });
 };
+var getSheetTranslationJobIds = ({ jobs }) => jobs.flatMap((job) => job.jobId ? [job.jobId] : []);
+var formatSheetTranslationOutput = ({ jobs }) => {
+  if (jobs.length === 0 || jobs.every((job) => job.jobId === null)) {
+    return "No sheet translation jobs queued.";
+  }
+  return jobs.map(
+    (job) => job.jobId ? `${job.jobId}  sheet ${job.exerciseSheetId}  ${job.language}` : `already complete  ${job.language}`
+  ).join("\n");
+};
 var formatAppendExercisesToSheetOutput = ({ receipt }) => {
   return formatAgentWriteReceiptOutput({ receipt });
 };
@@ -7983,6 +8191,111 @@ var registerSheetCommands = (sheetYargs, context) => {
         }
       );
     }
+  ).command(
+    "translate [exerciseSheetId]",
+    "Queue translation generation for an existing exercise sheet",
+    (translateYargs) => translateYargs.positional("exerciseSheetId", {
+      type: "string",
+      describe: "Exercise sheet ID to translate"
+    }).option("translate-to", {
+      array: true,
+      type: "string",
+      describe: `Generate translated sheet content for these languages (${translationLanguages2.join(", ")})`
+    }).option("source-language", {
+      type: "string",
+      describe: "Preferred source language for sheet metadata translation"
+    }).option("timeout-ms", {
+      type: "number",
+      default: 3e5,
+      describe: "Maximum time to wait before timing out"
+    }).option("wait", {
+      type: "boolean",
+      default: false,
+      describe: "Wait for queued translation jobs to finish"
+    }).example(
+      "chalksurf sheet translate 00000000-0000-4000-8000-000000000001 --translate-to english --json",
+      "Queue sheet translation generation"
+    ),
+    async (argv) => {
+      const id = resolveRequestedUuid2({
+        fallbackValue: argv.exerciseSheetId,
+        label: "exerciseSheetId",
+        required: true
+      });
+      const targetLanguages = resolveRequestedTranslateToLanguages(argv.translateTo);
+      if (!targetLanguages || targetLanguages.length === 0) {
+        throw new CliCommandError("--translate-to is required at least once.", 2);
+      }
+      const sourceLanguage = normalizeChoiceValues({
+        allowedValues: translationLanguages2,
+        label: "--source-language",
+        values: argv.sourceLanguage ? [argv.sourceLanguage] : void 0
+      })?.[0];
+      const input = {
+        id,
+        targetLanguages,
+        ...sourceLanguage === void 0 ? {} : { sourceLanguage }
+      };
+      const { apiClient, organizationId } = await createResolvedApiClient({
+        context,
+        baseUrlFlagValue: argv.baseUrl,
+        organizationFlagValue: argv.organization,
+        profileName: argv.profile
+      });
+      let result;
+      try {
+        result = await apiClient.agentStartSheetTranslationGeneration(input);
+      } catch (error) {
+        throw mapApiErrorToCliError(error);
+      }
+      if (argv.wait !== true) {
+        context.output.print(
+          {
+            request: {
+              ...input,
+              organizationId: organizationId ?? null,
+              wait: false,
+              timeoutMs: null
+            },
+            jobs: result.jobs
+          },
+          (output) => formatSheetTranslationOutput({ jobs: output.jobs }),
+          {
+            command: "sheet translate"
+          }
+        );
+        return;
+      }
+      const timeoutMs = normalizeWaitTimeoutMs(argv.timeoutMs);
+      const jobIds = getSheetTranslationJobIds(result);
+      const waitResult = jobIds.length === 0 ? { jobs: [], timedOut: false } : await waitForCliJobs({
+        getUserJob: async (jobId) => await apiClient.getUserJob(jobId),
+        jobIds,
+        now: context.now,
+        sleep: context.sleep,
+        timeoutMs
+      });
+      const waitError = getWaitError(waitResult);
+      context.output.print(
+        {
+          request: {
+            ...input,
+            organizationId: organizationId ?? null,
+            wait: true,
+            timeoutMs
+          },
+          jobs: result.jobs,
+          wait: waitResult
+        },
+        (output) => output.wait.jobs.length > 0 ? output.wait.jobs.map((job) => formatCliJobSummary(job)).join("\n") : formatSheetTranslationOutput({ jobs: output.jobs }),
+        {
+          command: "sheet translate",
+          ok: waitError == null,
+          error: waitError
+        }
+      );
+      throwSilentExitCode(getWaitExitCode(waitResult));
+    }
   ).command(
     "update [exerciseSheetId]",
     "Apply a field-level patch to an exercise sheet",

package/docs/agents.md

@@ -172,6 +172,7 @@ MCP clients should use tool discovery from the client. The ChalkSurf MCP endpoin
 | `exercise copy` | `copy_exercise` |
 | `exercise update` | `update_exercise` |
 | `exercise set-visibility` | `set_exercise_visibility` |
+| `exercise translate` | `generate_exercise_translation_job` |
 | `exercise delete` | `delete_exercise` |
 | `exercise validate-latex` | `validate_latex_snippets` |
 | `exercise import` | `import_exercise` |
@@ -186,6 +187,7 @@ MCP clients should use tool discovery from the client. The ChalkSurf MCP endpoin
 | `sheet append` | `append_exercises_to_sheet` |
 | `sheet update` | `update_sheet` |
 | `sheet set-visibility` | `set_sheet_visibility` |
+| `sheet translate` | `generate_sheet_translation_job` |
 | `sheet delete` | `delete_sheet` |
 | `sheet import` | `import_sheet` |
 | `sheet import-solutions` | `import_sheet_solutions` |

package/docs/manual.md

@@ -162,6 +162,15 @@ chalksurf job wait job_123 job_124
 
 `--wait` on an import command means the parsed content has been saved before the command exits. Requested translations run as separate jobs; use `--json` to capture their job IDs or `chalksurf job list` to inspect them later.
 
+Queue translations for existing resources:
+
+```bash
+chalksurf exercise translate 00000000-0000-4000-8000-000000000001 --translate-to english
+chalksurf sheet translate 00000000-0000-4000-8000-000000000002 --translate-to english --source-language hungarian
+```
+
+Add `--wait` to either translate command to wait for the queued translation job or jobs to finish.
+
 ## Searching From The CLI
 
 Search commands default to `--ownership own`, which means resources in the selected organization.

package/docs/mcp.md

@@ -43,6 +43,7 @@ Treat write receipts as an agent audit log. They are suitable for user-visible s
 | `delete_exercise` | write | Soft-delete one unused writable exercise after `updated_at` and exact-ID confirmation checks. |
 | `update_exercise` | write | Patch exercise fields with an `updated_at` precondition and shared-usage acknowledgement. |
 | `set_exercise_visibility` | write | Make one writable exercise public or private when visibility controls are enabled. |
+| `generate_exercise_translation_job` | write | Queue translation generation for one writable exercise. |
 | `import_exercise` | write | Queue an exercise import from MCP files or HTTPS URLs. |
 | `import_exercise_solution` | write | Queue a solution import for one exercise. |
 | `search_sheets` | read | Search visible sheets, optionally by readiness issues. |
@@ -56,6 +57,7 @@ Treat write receipts as an agent audit log. They are suitable for user-visible s
 | `update_sheet` | write | Patch sheet metadata with an `updated_at` precondition. |
 | `set_sheet_visibility` | write | Make one writable sheet public or private when visibility controls are enabled. |
 | `append_exercises_to_sheet` | write | Append existing visible exercises to the end of one writable sheet. |
+| `generate_sheet_translation_job` | write | Queue translation generation for one writable exercise sheet. |
 | `list_folders` | read | List sheet folders in the selected organization. |
 | `create_folder` | write | Create a sheet folder. |
 | `rename_folder` | write | Rename a sheet folder. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chalksurf/cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "private": false,
   "type": "module",
   "engines": {