@jutge.org/toolkit 4.1.0 → 4.2.1

package/toolkit/generate.ts

@@ -0,0 +1,213 @@
+import { Argument, Command } from '@commander-js/extra-typings'
+import { join } from 'path'
+import sharp from 'sharp'
+import { complete, generateImage } from '../lib/ai'
+import { languageKeys, languageNames, proglangKeys } from '../lib/data'
+import {
+    addAlternativeSolution,
+    addMainFile,
+    addStatementTranslation,
+    generateTestCasesGenerator,
+} from '../lib/generate'
+import { newProblem } from '../lib/problem'
+import { settings } from '../lib/settings'
+import tui from '../lib/tui'
+import { writeText } from '../lib/utils'
+import { createProblemWithJutgeAI } from '../lib/create-with-jutgeai'
+
+export const generateCmd = new Command('generate')
+    .description('Generate problem elements using JutgeAI')
+
+    .action(() => {
+        generateCmd.help()
+    })
+
+generateCmd
+    .command('problem')
+    .description('Generate a problem with JutgeAI')
+
+    .option('-d, --directory <path>', 'output directory', 'new-problem.pbm')
+    .option('-i, --input <path>', 'input specification file')
+    .option('-o, --output <path>', 'output specification file')
+    .option('-n, --do-not-ask', 'do not ask interactively if --input given', false)
+    .option('-m, --model <model>', 'AI model to use', settings.defaultModel)
+
+    .action(async ({ input, output, directory, model, doNotAsk }) => {
+        await createProblemWithJutgeAI(model, directory, input, output, doNotAsk)
+    })
+
+generateCmd
+    .command('translations')
+    .summary('Generate statement translations using JutgeAI')
+    .description(
+        `Generate statement translations using JutgeAI
+    
+Use this command to add translations of the problem statement into different languages.
+The original statement will be used as the source text for translation.
+
+Provide one or more target language from the following list:
+${Object.entries(languageNames)
+    .map(([key, name]) => `  - ${key}: ${name}`)
+    .join('\n')}
+
+The added translations will be saved in the problem directory overwrite possible existing files.`,
+    )
+
+    .addArgument(new Argument('<languages...>', 'languages to add').choices(languageKeys))
+    .option('-d, --directory <path>', 'problem directory', '.')
+    .option('-m, --model <model>', 'AI model to use', settings.defaultModel)
+
+    .action(async (languages, { directory, model }) => {
+        const problem = await newProblem(directory)
+        await tui.section('Generating statement translations', async () => {
+            for (const language of languages) {
+                await addStatementTranslation(model, problem, language)
+            }
+        })
+    })
+
+generateCmd
+    .command('solutions')
+    .summary('Generate alternative solutions using JutgeAI')
+    .description(
+        `Generate alternative solutions using JutgeAI
+
+Use this command to add alternative solutions for the problem in different programming languages.
+The golden solution will be used as a reference for generating the alternatives.
+
+Provide one or more target programming languages from the following list:
+${Object.entries(languageNames)
+    .map(([key, name]) => `  - ${key}: ${name}`)
+    .join('\n')}
+
+The added solutions will be saved in the problem directory overwrite possible existing files.`,
+    )
+
+    .addArgument(new Argument('<proglangs...>', 'proglangs to add').choices(proglangKeys))
+    .option('-d, --directory <path>', 'problem directory', '.')
+    .option('-m, --model <model>', 'AI model to use', settings.defaultModel)
+
+    .action(async (proglangs, { directory, model }) => {
+        const problem = await newProblem(directory)
+        for (const proglang of proglangs) {
+            await addAlternativeSolution(model, problem, proglang)
+        }
+    })
+
+generateCmd
+    .command('mains')
+    .summary('Generate main files using JutgeAI')
+    .description(
+        `Generate main files using JutgeAI
+
+Main files are the entry point for problems that ask users to implement specific functions or classes.
+
+Use this command to add main files for the problem in different programming languages.
+The main file for the golden solution will be used as a reference for generating the main files.
+
+Provide one or more target programming languages from the following list:
+${Object.entries(languageNames)
+    .map(([key, name]) => `  - ${key}: ${name}`)
+    .join('\n')}
+
+The added main files will be saved in the problem directory overwrite possible existing files.`,
+    )
+
+    .addArgument(new Argument('<proglangs...>', 'proglangs to add').choices(proglangKeys))
+    .option('-d, --directory <path>', 'problem directory', '.')
+    .option('-m, --model <model>', 'AI model to use', settings.defaultModel)
+
+    .action(async (proglangs, { directory, model }) => {
+        const problem = await newProblem(directory)
+        for (const proglang of proglangs) {
+            await addMainFile(model, problem, proglang)
+        }
+    })
+
+generateCmd
+    .command('generators')
+    .summary('Generate test cases generators using JutgeAI')
+
+    .option('--random', 'generate a generator for random test cases')
+    .option('--hard', 'generate a generator for hard test cases')
+    .option('--efficiency', 'generate a generator for efficiency test cases')
+    .option('--all', 'generate all three test case generators')
+
+    .option('-d, --directory <path>', 'problem directory', '.')
+    .option('-o, --output <path>', 'output file', 'generator-{{type}}.py')
+    .option('-m, --model <model>', 'AI model to use', settings.defaultModel)
+
+    .action(async ({ efficiency, hard, random, all, directory, model, output }) => {
+        const problem = await newProblem(directory)
+        await tui.section('Generating test cases generators', async () => {
+            if (all || random) await generateTestCasesGenerator(model, problem, output, 'random')
+            if (all || hard) await generateTestCasesGenerator(model, problem, output, 'hard')
+            if (all || efficiency) await generateTestCasesGenerator(model, problem, output, 'efficiency')
+        })
+    })
+
+generateCmd
+    .command('award.png')
+    .summary('Generate award.png using JutgeAI')
+    .description(
+        `Generate award.png using AI
+    
+Use this command to add an award image for the problem.
+Awards are shown to users when they solve the problem.
+They help to motivate users and make the platform more engaging.
+
+Provide an interesting prompt to customize the image content. For example:
+    - "A golden trophy with a blue ribbon on a wooden base."
+    - "A star made of sparkling diamonds on a black background."
+    - "A minimalist image with a white background using Van Gogh style."
+
+The new image will be saved as award.png in the problem directory, overriding any existing file.`,
+    )
+
+    .option('-d, --directory <path>', 'problem directory', '.')
+    .option('-m, --model <model>', 'graphic AI model to use', 'openai/dall-e-3')
+    .argument('[prompt]', 'prompt to generate the image', 'A colorful image on a white background. ')
+
+    .action(async (prompt, { directory, model }) => {
+        const output = join(directory, 'award.png')
+        const problem = await newProblem(directory)
+        const image = await generateImage(model, prompt)
+        await sharp(image).resize(512, 512).toFile(output)
+        await tui.image(output, 20, 10)
+        tui.success(`Added ${output}`)
+    })
+
+generateCmd
+    .command('award.html')
+    .summary('Generate award.html using JutgeAI')
+    .description(
+        `Generate award.html using JutgeAI
+
+Use this command to add an award message for the problem.
+Awards are shown to users when they solve the problem.
+They help to motivate users and make the platform more engaging.
+
+Provide an interesting prompt to customize the message content. For example:
+- "A short encouraging message after having solved a challenge or a problem."
+- "A congratulatory message for completing a difficult task."
+- "A motivational quote to inspire further learning."
+
+The new message will be saved as award.html in the problem directory, overriding any existing file.`,
+    )
+
+    .option('-d, --directory <path>', 'problem directory', '.')
+    .argument(
+        '[prompt]',
+        'prompt to generate the award message',
+        'Only provide a short encouraging message after having solved a challenge or a problem. Nothing else!',
+    )
+    .option('-m, --model <model>', 'AI model to use', settings.defaultModel)
+
+    .action(async (prompt, { directory, model }) => {
+        const output = join(directory, 'award.html')
+        const problem = await newProblem(directory)
+        const message = await complete(model, '', prompt)
+        tui.print(message)
+        await writeText(output, message)
+        tui.success(`Added ${output}`)
+    })

package/toolkit/index.ts

@@ -0,0 +1,63 @@
+#!/usr/bin/env bun
+
+import { program } from '@commander-js/extra-typings'
+import { ZodError } from 'zod'
+import { fromError } from 'zod-validation-error'
+import { settings } from '../lib/settings'
+import { packageJson } from '../lib/versions'
+import { aboutCmd } from './about'
+import { aiCmd } from './ai'
+import { verifyCmd } from './verify'
+import { cleanCmd } from './clean'
+import { compilersCmd } from './compilers'
+import { configCmd } from './config'
+import { cloneCmd } from './clone'
+import { doctorCmd } from './doctor'
+import { generateCmd } from './generate'
+import { makeCmd } from './make'
+import { quizCmd } from './quiz'
+import { upgradeCmd } from './upgrade'
+import { uploadCmd } from './upload'
+import { askCmd } from './ask'
+
+program.name(Object.keys(packageJson.bin as Record<string, string>)[0] as string)
+program.alias(Object.keys(packageJson.bin as Record<string, string>)[1] as string)
+program.version(packageJson.version)
+program.description(packageJson.description!)
+program.helpCommand('help [command]', 'Display help for command') // To get the message with uppercase :-)
+
+program.addCommand(configCmd)
+program.addCommand(cloneCmd)
+program.addCommand(generateCmd)
+program.addCommand(makeCmd)
+program.addCommand(uploadCmd)
+program.addCommand(cleanCmd)
+program.addCommand(verifyCmd)
+program.addCommand(doctorCmd)
+if (settings.developer) {
+    program.addCommand(quizCmd)
+    program.addCommand(compilersCmd)
+    program.addCommand(aiCmd)
+}
+program.addCommand(upgradeCmd)
+program.addCommand(aboutCmd)
+program.addCommand(askCmd)
+
+try {
+    await program.parseAsync()
+} catch (error) {
+    console.log()
+    console.error('An error occurred:')
+    if (error instanceof Error) {
+        if (error.name === 'ExitPromptError') {
+            console.error('Operation cancelled by the user')
+        } else if (error instanceof ZodError) {
+            console.error(fromError(error).toString())
+        } else {
+            console.error(error.message)
+            if (settings.developer) console.error(error)
+        }
+    } else {
+        console.error(error)
+    }
+}

package/toolkit/make.ts

@@ -0,0 +1,92 @@
+import { Command } from '@commander-js/extra-typings'
+import { join, resolve } from 'path'
+import { findRealDirectories } from '../lib/helpers'
+import { newMaker } from '../lib/maker'
+import tui from '../lib/tui'
+import { nothing, projectDir } from '../lib/utils'
+
+export const makeCmd = new Command('make')
+    .description('Make problem elements')
+
+    .argument('[tasks...]', 'tasks to make: all|info|exe|cor|pdf|txt|md|html', ['all'])
+    .option('-d, --directories <directories...>', 'problem directories', ['.'])
+    .option('-i, --ignore-errors', 'ignore errors on a directory and continue processing', false)
+    .option('-e, --only-errors', 'only show errors at the final summary', false)
+
+    .action(async (tasks, { directories, ignoreErrors, onlyErrors }) => {
+        if (tasks.length === 0) {
+            tasks = ['all']
+        }
+        if (tasks.includes('all') && tasks.length > 1) {
+            throw new Error("When 'all' is specified, no other tasks should be provided")
+        }
+        if (!tasks.every((t) => ['all', 'info', 'exe', 'cor', 'pdf', 'txt', 'md', 'html'].includes(t))) {
+            throw new Error('Tasks must be one of: all, info, exe, cor, pdf, txt, md, html')
+        }
+
+        console.log()
+        await tui.image(join(projectDir(), 'assets', 'images', 'jutge-toolkit.png'), 8, 4)
+
+        const errors: Record<string, string> = {} // directory -> error message
+
+        const realDirectories = await findRealDirectories(directories)
+
+        for (const directory of realDirectories) {
+            try {
+                tui.title(`Making problem in directory ${tui.hyperlink(directory, resolve(directory))}`)
+
+                const maker = await newMaker(directory)
+
+                // If tasks include 'all', run makeProblem
+                if (tasks.includes('all')) {
+                    await maker.makeProblem()
+                } else {
+                    // Run specific tasks
+                    if (tasks.includes('info')) {
+                        // already done in maker initialization
+                    }
+                    if (tasks.includes('exe')) {
+                        await maker.makeExecutables()
+                    }
+                    if (tasks.includes('cor')) {
+                        await maker.makeCorrects()
+                    }
+                    if (tasks.includes('pdf')) {
+                        await maker.makePdfStatements()
+                    }
+                    if (tasks.includes('txt') || tasks.includes('html') || tasks.includes('md')) {
+                        await maker.makeTextualStatements(
+                            tasks.filter((t) => ['txt', 'html', 'md'].includes(t)) as Array<'txt' | 'html' | 'md'>,
+                        )
+                    }
+                }
+            } catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error)
+
+                if (ignoreErrors) {
+                    errors[directory] = errorMessage
+                    tui.error(`Error: ${errorMessage}`)
+                } else {
+                    throw error
+                }
+            }
+            console.log()
+        }
+
+        tui.title('Summary')
+        await tui.section('', async () => {
+            await nothing()
+            if (realDirectories.length === 0) {
+                tui.warning('No problem directories found')
+            }
+            for (const directory of realDirectories) {
+                if (errors[directory]) {
+                    tui.directory(directory)
+                    tui.error(`  ${errors[directory]}`)
+                } else if (!onlyErrors) {
+                    tui.directory(directory)
+                    tui.success(`  No errors found`)
+                }
+            }
+        })
+    })

package/toolkit/quiz.ts

@@ -0,0 +1,44 @@
+import { Command } from '@commander-js/extra-typings'
+import { makeQuiz, validateQuiz } from '../lib/quiz'
+import tui from '../lib/tui'
+import { findRealDirectories } from '../lib/helpers'
+import { random } from 'radash'
+
+export const quizCmd = new Command('quiz')
+    .description('Commands related to quizzes')
+
+    .action(() => {
+        quizCmd.help()
+    })
+
+quizCmd
+    .command('validate')
+    .description('Validate a quiz problem')
+
+    .option('-d, --directories <directories...>', 'problem directories', ['.'])
+
+    .action(async ({ directories }) => {
+        const realDirectories = await findRealDirectories(directories)
+        for (const directory of realDirectories) {
+            await tui.section(`Validating quiz in directory ${tui.hyperlink(directory)}`, async () => {
+                await validateQuiz(directory)
+            })
+        }
+    })
+
+quizCmd
+    .command('make')
+    .description('Make a quiz problem')
+
+    .option('-d, --directory <directory>', 'problem directory', '.')
+    .option('-s, --seed <seed>', 'random seed')
+
+    .action(async ({ directory, seed }) => {
+        tui.warning('The quiz make command is work-in-progress and may not work as expected yet.')
+        const realDirectories = await findRealDirectories([directory])
+        const seedValue = seed ? parseInt(seed, 10) : random(1000000, 9999999)
+        for (const directory of realDirectories) {
+            await makeQuiz(directory, seedValue)
+            return // in this case we only process one directory as quizzes should only have one language
+        }
+    })

package/toolkit/upgrade.ts

@@ -0,0 +1,9 @@
+import { Command } from '@commander-js/extra-typings'
+import { upgrade } from '../lib/versions'
+
+export const upgradeCmd = new Command('upgrade')
+    .description('Upgrade to the latest version')
+
+    .action(async () => {
+        await upgrade()
+    })

package/toolkit/upload.ts

@@ -0,0 +1,20 @@
+import { Command } from '@commander-js/extra-typings'
+import { uploadProblem } from '../lib/upload'
+import { newProblem } from '../lib/problem'
+
+export const uploadCmd = new Command('upload')
+    .summary('Upload problem to Jutge.org')
+    .description(
+        `Upload problem to Jutge.org
+
+If problem.yml exists, the problem will be updated at Jutge.org using that information (which includes its problem id).
+If problem.yml does not exist, a new problem will be created at Jutge.org and problem.yml will be generated.
+`,
+    )
+
+    .option('-d, --directory <directory>', 'problem directory', '.')
+
+    .action(async ({ directory }) => {
+        const problem = await newProblem(directory)
+        await uploadProblem(problem)
+    })

package/toolkit/verify.ts

@@ -0,0 +1,15 @@
+import { Command } from '@commander-js/extra-typings'
+import { newMaker } from '../lib/maker'
+
+export const verifyCmd = new Command('verify')
+    .description('Verify programs against golden solution')
+
+    .argument('<programs...>', 'source programs to verify')
+    .option('-d, --directory <path>', 'problem directory', '.')
+
+    .action(async (programs, { directory }) => {
+        const maker = await newMaker(directory)
+        for (const program of programs) {
+            await maker.verifyCandidate(program)
+        }
+    })