@jutge.org/toolkit 4.0.5 → 4.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@jutge.org/toolkit",
     "description": "Toolkit to prepare problems for Jutge.org",
-    "version": "4.0.5",
+    "version": "4.2.0",
     "homepage": "https://jutge.org",
     "author": {
         "name": "Jutge.org",
@@ -40,6 +40,8 @@
     },
     "files": [
         "dist",
+        "toolkit",
+        "docs",
         "assets"
     ],
     "dependencies": {

package/toolkit/about.ts

@@ -0,0 +1,40 @@
+import { Command } from '@commander-js/extra-typings'
+import chalk from 'chalk'
+import tui from '../lib/tui.ts'
+import { nothing } from '../lib/utils.ts'
+import { packageJson } from '../lib/versions.ts'
+
+export const aboutCmd = new Command('about')
+    .description('Get information about jutge-toolkit')
+
+    .action(async () => {
+        await nothing()
+        tui.print(chalk.bold(`jutge-toolkit ${packageJson.version}`))
+        tui.print(packageJson.description)
+        tui.print('')
+        tui.url(packageJson.homepage!)
+        tui.print('')
+        tui.print('Author:')
+        showPerson(packageJson.author!)
+        tui.print('')
+        tui.print('Contributors:')
+        for (const contributor of packageJson.contributors!) {
+            showPerson(contributor)
+        }
+    })
+
+function showPerson(person: string | { name: string; email?: string; url?: string }) {
+    let line = '    - '
+    if (typeof person === 'string') {
+        line += person
+    } else {
+        line += person.name
+        if (person.email) {
+            line += ` <${tui.link('mailto://' + person.email, person.email)}>`
+        }
+        if (person.url) {
+            line += ` (${tui.link(person.url)})`
+        }
+    }
+    tui.print(line)
+}

package/toolkit/ai.ts

@@ -0,0 +1,56 @@
+import { Command } from '@commander-js/extra-typings'
+import sharp from 'sharp'
+import z from 'zod'
+import { complete, generateImage, listModels } from '../lib/ai.ts'
+import { settings } from '../lib/settings.ts'
+import tui from '../lib/tui.ts'
+import { convertStringToItsType } from '../lib/utils.ts'
+
+export const aiCmd = new Command('ai')
+    .description('Query AI models')
+
+    .action(() => {
+        aiCmd.help()
+    })
+
+aiCmd
+    .command('models')
+    .description('Show available AI models')
+
+    .action(async () => {
+        const models = await listModels()
+        tui.yaml(models)
+    })
+
+aiCmd
+    .command('complete')
+    .description('Complete a prompt using an AI model')
+
+    .argument('<prompt>', 'the user prompt to complete')
+    .option('-s, --system-prompt <system>', 'the system prompt to use', 'You are a helpful assistant.')
+    .option('-m, --model <model>', 'the AI model to use', settings.defaultModel)
+
+    .action(async (prompt, { model, systemPrompt }) => {
+        prompt = prompt.trim()
+        systemPrompt = systemPrompt.trim()
+        const answer = await complete(model, systemPrompt, prompt)
+        tui.print(answer)
+    })
+
+// TODO: generate with different aspect ratios
+aiCmd
+    .command('image')
+    .description('Generate a square image using an AI model')
+
+    .argument('<prompt>', 'description of the image to generate')
+    .option('-m, --model <model>', 'the graphic AI model to use', 'openai/dall-e-3')
+    .option('-s, --size <size>', 'the size of the image (in pixels)', '1024')
+    .option('-o, --output <path>', 'the output image path', 'image.png')
+
+    .action(async (prompt, { model, size, output }) => {
+        const sizeInt = z.int().min(16).max(2048).parse(convertStringToItsType(size))
+        const image = await generateImage(model, prompt)
+        await sharp(image).resize(sizeInt, sizeInt).toFile(output)
+        tui.success(`Generated image saved to ${output}`)
+        await tui.image(output, 20, 10)
+    })

package/toolkit/ask.ts

@@ -0,0 +1,45 @@
+import { Command } from '@commander-js/extra-typings'
+import { glob } from 'fs/promises'
+import { complete } from '../lib/ai'
+import { settings } from '../lib/settings'
+import tui from '../lib/tui'
+import { projectDir, readTextInDir } from '../lib/utils'
+import { join } from 'path'
+import { all } from 'radash'
+
+export const askCmd = new Command('ask')
+    .description('Ask questions about jutge-toolkit to JutgeAI')
+
+    .argument('[question]', 'your question about the toolkit')
+    .option('-m, --model <model>', 'AI model to use', settings.defaultModel)
+
+    .action(async (question, { model }) => {
+        if (!question || question.trim().length === 0) {
+            askCmd.help()
+            return
+        }
+
+        const systemPrompt = await readTextInDir(join(projectDir(), 'assets', 'prompts', 'ask'), 'ask.md')
+
+        const docs = await loadDocumentation() // Load your markdown files
+        const fullPrompt = `${docs}\n\nUser question: ${question}`
+
+        const answer = await complete(model, systemPrompt, fullPrompt)
+        await tui.markdown(answer)
+        tui.warning(`This answer was generated by JutgeAI using model (${model}).`)
+    })
+
+export async function loadDocumentation(): Promise<string> {
+    const documentsDir = join(projectDir(), 'docs')
+    const toolkitDir = join(projectDir(), 'toolkit')
+
+    const documentPaths = await Array.fromAsync(glob('*.md', { cwd: documentsDir }))
+    const sourcePaths = await Array.fromAsync(glob('*.ts', { cwd: toolkitDir }))
+
+    const documents = await all(documentPaths.map((file) => readTextInDir(documentsDir, file)))
+    const sources = await all(sourcePaths.map((file) => readTextInDir(toolkitDir, file)))
+
+    const texts = [...documents, ...sources]
+
+    return texts.join('\n\n')
+}

package/toolkit/clean.ts

@@ -0,0 +1,25 @@
+import { Command, Option } from '@commander-js/extra-typings'
+import { cleanDirectory } from '../lib/cleaner'
+import tui from '../lib/tui'
+import { findRealDirectories } from '../lib/helpers'
+
+export const cleanCmd = new Command('clean')
+    .description('Clean disposable files')
+
+    .option('-d, --directories <directories...>', 'problem directories', ['.'])
+    .option('-a, --all', 'clean all disposable files (including generated statement and correct files', false)
+    .addOption(new Option('-f, --force', 'force removal').conflicts('dryRun'))
+    .addOption(new Option('-n, --dry-run', 'show but do not remove files').conflicts('force'))
+
+    .action(async ({ directories, all, force, dryRun }) => {
+        const isForce = force || false // default to dry-run if neither option is specified
+
+        await tui.section(`Cleaning generated files`, async () => {
+            const realDirectories = await findRealDirectories(directories)
+            for (const directory of realDirectories) {
+                await tui.section(`Cleaning directory ${tui.hyperlink(directory)}`, async () => {
+                    await cleanDirectory(isForce, all, directory)
+                })
+            }
+        })
+    })

package/toolkit/clone.ts

@@ -0,0 +1,12 @@
+import { Command } from '@commander-js/extra-typings'
+import { createProblemWithTemplate } from '../lib/create-with-template'
+
+export const cloneCmd = new Command('clone')
+    .description('Clone a template into a new problem')
+
+    .argument('[template]', 'template to use (empty to interactive selection)')
+    .option('-d, --directory <path>', 'output directory', 'new-problem.pbm')
+
+    .action(async (template, { directory }) => {
+        await createProblemWithTemplate(directory, template)
+    })

package/toolkit/compilers.ts

@@ -0,0 +1,29 @@
+import { getAvailableCompilers, getCompilersInfo, getDefinedCompilerIds } from '../lib/compilers'
+import { Command } from '@commander-js/extra-typings'
+
+export const compilersCmd = new Command('compilers')
+    .description('Query compiler information')
+    // default action is to list all compilers because of older compatibility
+
+    .action(async () => {
+        const info = await getCompilersInfo()
+        console.dir(info)
+    })
+
+compilersCmd
+    .command('list-defined')
+    .description('List all defined compiler names')
+
+    .action(async () => {
+        const items = await getDefinedCompilerIds()
+        console.dir(items)
+    })
+
+compilersCmd
+    .command('list-available')
+    .description('List all available compiler names')
+
+    .action(async () => {
+        const items = await getAvailableCompilers()
+        console.dir(items)
+    })

package/toolkit/config.ts

@@ -0,0 +1,113 @@
+import { Command } from '@commander-js/extra-typings'
+import { confirm } from '@inquirer/prompts'
+import { editor } from '@inquirer/prompts'
+import YAML from 'yaml'
+import { ZodError } from 'zod'
+import { fromError } from 'zod-validation-error'
+import { configPath, loadSettings, saveSettings, settings } from '../lib/settings'
+import { Settings } from '../lib/types.ts'
+import tui from '../lib/tui.ts'
+import { convertStringToItsType } from '../lib/utils.ts'
+
+export const configCmd = new Command('config')
+    .summary('Manage configuration')
+    .description(
+        `Manage configuration
+    
+The actual configuration file is stored at ${configPath()}`,
+    )
+
+    .action(() => {
+        configCmd.help()
+    })
+
+configCmd
+    .command('show')
+    .alias('list')
+    .description('Show configuration options')
+
+    .action(async () => {
+        const settings = await loadSettings()
+        tui.yaml(settings)
+    })
+
+configCmd
+    .command('get <key>')
+    .description('Get the value of a configuration option')
+
+    .action((key: string) => {
+        if (!(key in settings)) {
+            throw new Error(`Configuration key ${key} does not exist`)
+        }
+        console.log((settings as any)[key])
+    })
+
+configCmd
+    .command('set <key> <value>')
+    .description('Set the value of a configuration option')
+
+    .action(async (key: string, value: string) => {
+        if (!(key in settings)) {
+            throw new Error(`Configuration key ${key} does not exist`)
+        }
+        const convertedValue = convertStringToItsType(value)
+        const newSettings = Settings.parse({ ...settings, [key]: convertedValue })
+        await saveSettings(newSettings)
+        tui.success(`Configuration key ${key} updated successfully`)
+    })
+
+configCmd
+    .command('edit')
+    .description('Open an editor (uses $EDITOR or $VISUAL) to modify the configuration options')
+
+    .action(async () => {
+        let data = YAML.stringify(settings, null, 4)
+        while (true) {
+            const newData = await editor({
+                message: 'Edit configuration',
+                default: data,
+                postfix: '.yml',
+                waitForUserInput: false,
+            })
+            try {
+                const newSettings = Settings.parse(YAML.parse(newData))
+                await saveSettings(newSettings)
+                tui.success('Configuration options updated successfully')
+                return
+            } catch (error) {
+                if (error instanceof ZodError) {
+                    console.error(fromError(error).toString())
+                } else {
+                    console.error(error)
+                }
+                const again = await confirm({ message: 'Edit again?', default: true })
+                if (!again) {
+                    tui.warning('No changes made to the configuration options')
+                    return
+                }
+                data = newData
+            }
+        }
+    })
+
+configCmd
+    .command('reset')
+    .description('Reset configuration to default values')
+
+    .option('-f, --force', 'force reset without confirmation', false)
+
+    .action(async ({ force }) => {
+        if (!force) {
+            const confirmReset = await confirm({
+                message: 'Are you sure you want to reset the configuration to default values?',
+                default: false,
+            })
+            if (!confirmReset) {
+                tui.warning('Reset cancelled')
+                return
+            }
+        }
+        const defaultSettings = Settings.parse({})
+        await saveSettings(defaultSettings)
+        tui.success('Configuration reset to default values successfully')
+    })

package/toolkit/create.ts

@@ -0,0 +1,36 @@
+import { Command } from '@commander-js/extra-typings'
+import { createProblemWithJutgeAI } from '../lib/create-with-jutgeai'
+import { createProblemWithTemplate } from '../lib/create-with-template'
+import { settings } from '../lib/settings'
+
+export const createCmd = new Command('create')
+    .description('Create a new problem')
+
+    .action(() => {
+        createCmd.help()
+    })
+
+createCmd
+    .command('with-template')
+    .description('Create a problem with a template')
+
+    .argument('[template]', 'template to use (empty to interactive selection)')
+    .option('-d, --directory <path>', 'output directory', 'new-problem.pbm')
+
+    .action(async (template, { directory }) => {
+        await createProblemWithTemplate(directory, template)
+    })
+
+createCmd
+    .command('with-ai')
+    .description('Create 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)
+    })

package/toolkit/doctor.ts

@@ -0,0 +1,22 @@
+import * as doc from '../lib/doctor'
+import { Command } from '@commander-js/extra-typings'
+import tui from '../lib/tui'
+
+export const doctorCmd = new Command('doctor')
+    .description('Diagnose status of the environment')
+
+    .action(async () => {
+        await tui.section('Perform checks', async () => {
+            await tui.section('Checking Python3 installation', doc.checkPython3)
+            await tui.section('Checking C/C++ installation', doc.checkGCC)
+            await tui.section('Checking Haskell installation', doc.checkHaskell)
+            await tui.section('Checking Clojure installation', doc.checkClojure)
+            await tui.section('Checking Java installation', doc.checkJava)
+            await tui.section('Checking Rust installation', doc.checkRust)
+            await tui.section('Checking XeLaTeX installation', doc.checkXeLaTeX)
+            await tui.section('Checking Pandoc installation', doc.checkPandoc)
+            await tui.section('Checking ImageMagick installation', doc.checkImageMagick)
+            await tui.section('Checking AI models', doc.checkAIEnvVars)
+            await tui.section('Checking terminal', doc.checkTerminal)
+        })
+    })

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)
+    }
+}