@jutge.org/toolkit 4.4.6 → 4.4.9

package/docs/getting-started-guide.md

@@ -170,6 +170,12 @@ This will run the solution against all test cases and compare outputs.
 
 ### Generating Additional Content
 
+**Generate a statement from a solution:**
+
+```bash
+jtk generate statement cc en "Add a cute story about Joan."
+```
+
 **Add statement translations:**
 
 ```bash

package/docs/jutge-ai.md

@@ -61,7 +61,7 @@ See https://platform.openai.com/docs/pricing for the pricing of the OpenAI model
 
 ### Recommendation
 
-Try to use `gpt-4.1-nano` or `gpt-4.1-mini` for the quickest results. If you need more reliable results, use `gpt-5-nano` or `gpt-5-mini`.
+Try to use `gpt-4.1-nano` or `gpt-4.1-mini` for the quickest results. If you need more reliable results, use `gpt-5-nano` or `gpt-5-mini`. As could be expected, the larger the model, the more reliable the results and the slower the generation.
 
 # Jutge<sup>AI</sup> costs
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@jutge.org/toolkit",
     "description": "Toolkit to prepare problems for Jutge.org",
-    "version": "4.4.6",
+    "version": "4.4.9",
     "homepage": "https://jutge.org",
     "author": {
         "name": "Jutge.org",
@@ -65,6 +65,7 @@
         "@dicebear/core": "^9.3.1",
         "@eslint/js": "^9.39.2",
         "@inquirer/prompts": "^8.2.0",
+        "adm-zip": "^0.5.16",
         "archiver": "^7.0.1",
         "boxen": "^8.0.1",
         "bun-types": "^1.3.7",
@@ -94,6 +95,7 @@
         "zod-validation-error": "^5.0.0"
     },
     "devDependencies": {
+        "@types/adm-zip": "^0.5.0",
         "@types/archiver": "^7.0.0",
         "@types/image-size": "^0.8.0",
         "@types/node": "^25.1.0",

package/toolkit/clean.ts

@@ -2,20 +2,21 @@ import { Command, Option } from '@commander-js/extra-typings'
 import { cleanDirectory } from '../lib/cleaner'
 import tui from '../lib/tui'
 import { findRealDirectories } from '../lib/helpers'
+import { resolve } from 'path'
 
 export const cleanCmd = new Command('clean')
     .description('Clean disposable files')
 
-    .option('-d, --directories <directories...>', 'problem directories', ['.'])
+    .option('-d, --directory <directory>', 'problem directory', '.')
     .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 }) => {
+    .action(async ({ directory, 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)
+        await tui.section(`Cleaning disposable files in ${tui.hyperlink(resolve(directory))}`, async () => {
+            const realDirectories = await findRealDirectories([directory])
             for (const directory of realDirectories) {
                 await tui.section(`Cleaning directory ${tui.hyperlink(directory)}`, async () => {
                     await cleanDirectory(isForce, all, directory)

package/toolkit/convert.ts

@@ -15,10 +15,10 @@ convertCmd
     .command('transform-at-signs')
     .description('Transform @ signs to lstinline')
 
-    .option('-d, --directories <directories...>', 'problem directories', ['.'])
+    .option('-d, --directory <directory>', 'problem directory', '.')
 
-    .action(async ({ directories }) => {
-        const realDirectories = await findRealDirectories(directories)
+    .action(async ({ directory }) => {
+        const realDirectories = await findRealDirectories([directory])
 
         for (const realDirectory of realDirectories) {
             await tui.section(`Processing ${realDirectory}`, async () => {

package/toolkit/download.ts

@@ -0,0 +1,16 @@
+import { Command } from '@commander-js/extra-typings'
+import { downloadProblem } from '../lib/download'
+
+export const downloadCmd = new Command('download')
+    .summary('Download a problem from Jutge.org')
+
+    .argument('<problem_nm>', 'problem to download')
+    .option('-d, --directory <path>', 'output directory (default: <problem_nm>.pbm)')
+
+    .action(async (problem_nm, { directory }) => {
+        const outDir = directory ?? `${problem_nm}.pbm`
+        if (!outDir.endsWith('.pbm')) {
+            throw new Error('Output directory must end with .pbm')
+        }
+        await downloadProblem(problem_nm, outDir)
+    })

package/toolkit/dummies.ts

@@ -0,0 +1,219 @@
+import { Command } from '@commander-js/extra-typings'
+import type { Option, Argument } from '@commander-js/extra-typings'
+import { confirm, input, select } from '@inquirer/prompts'
+
+type CommandUnknownOpts = Command<unknown[], Record<string, unknown>, Record<string, unknown>>
+
+function getVisibleSubcommands(cmd: CommandUnknownOpts): CommandUnknownOpts[] {
+    const help = cmd.createHelp()
+    return help.visibleCommands(cmd).filter((c) => c.name() !== 'help')
+}
+
+function getVisibleOptions(cmd: CommandUnknownOpts): Option[] {
+    return cmd.options.filter((o) => !o.hidden && o.long !== 'help' && o.long !== 'version' && !o.negate)
+}
+
+function getVisibleArguments(cmd: CommandUnknownOpts): Argument[] {
+    return [...cmd.registeredArguments]
+}
+
+function commandSummary(cmd: CommandUnknownOpts): string {
+    const summary = (cmd as CommandUnknownOpts & { summary?: () => string }).summary?.()
+    if (summary) return summary
+    const desc = cmd.description()
+    return desc ? desc.split('\n')[0]!.trim() : cmd.name()
+}
+
+async function chooseCommand(
+    program: CommandUnknownOpts,
+    path: string[],
+): Promise<{ path: string[]; cmd: CommandUnknownOpts }> {
+    const current = path.length === 0 ? program : resolveCommand(program, path)!
+    const subcommands = getVisibleSubcommands(current)
+
+    if (subcommands.length === 0) {
+        return { path, cmd: current }
+    }
+
+    const choices = subcommands.map((c) => ({
+        name: `${c.name()} — ${commandSummary(c)}`,
+        value: c.name(),
+    }))
+
+    const chosen = await select({
+        message: path.length === 0 ? 'What do you want to do?' : `Choose ${current.name()} subcommand:`,
+        choices: [...choices, { name: '← Back', value: '__back__' }],
+    })
+
+    if (chosen === '__back__') {
+        if (path.length === 0) return { path: [], cmd: program }
+        return chooseCommand(program, path.slice(0, -1))
+    }
+
+
+    const newPath = [...path, chosen]
+    const nextCmd = resolveCommand(program, newPath)!
+    const nextSubs = getVisibleSubcommands(nextCmd)
+    if (nextSubs.length > 0) {
+        return chooseCommand(program, newPath)
+    }
+    return { path: newPath, cmd: nextCmd }
+}
+
+function resolveCommand(program: CommandUnknownOpts, path: string[]): CommandUnknownOpts | null {
+    let current: CommandUnknownOpts = program
+    for (const name of path) {
+        const sub = current.commands.find((c) => c.name() === name)
+        if (!sub) return null
+        current = sub as CommandUnknownOpts
+    }
+    return current
+}
+
+async function promptForArgument(arg: Argument, existing: string[]): Promise<string | string[]> {
+    const name = arg.name()
+    const desc = arg.description || name
+    const defaultVal = arg.defaultValue
+    const choices = arg.argChoices
+    const variadic = arg.variadic
+    const required = arg.required
+
+    const message = desc + (required ? '' : ' (optional)')
+
+    if (choices && choices.length > 0) {
+        const value = await select({
+            message,
+            choices: choices.map((c) => ({ name: c, value: c })),
+            default: defaultVal != null ? (Array.isArray(defaultVal) ? defaultVal[0] : defaultVal) : undefined,
+        })
+        return value
+    }
+
+    const defaultStr =
+        defaultVal != null
+            ? (Array.isArray(defaultVal) ? defaultVal.join(' ') : String(defaultVal))
+            : required
+                ? undefined
+                : ''
+
+    const raw = await input({
+        message,
+        default: defaultStr,
+        validate: (v) => (required && !v.trim() ? 'This argument is required' : true),
+    })
+
+    if (variadic && raw.includes(' ')) {
+        return raw.trim().split(/\s+/).filter(Boolean)
+    }
+    return raw.trim() || (defaultStr as string)
+}
+
+async function promptForOption(opt: Option): Promise<{ name: string; value: unknown } | null> {
+    const attr = opt.attributeName()
+    const desc = opt.description || opt.long || opt.flags
+    const defaultVal = opt.defaultValue
+    const choices = opt.argChoices
+    const isBool = opt.isBoolean()
+
+    if (isBool) {
+        const value = await confirm({
+            message: desc,
+            default: defaultVal === true,
+        })
+        return { name: attr, value }
+    }
+
+    if (choices && choices.length > 0) {
+        const value = await select({
+            message: desc,
+            choices: choices.map((c) => ({ name: c, value: c })),
+            default: defaultVal != null ? String(defaultVal) : undefined,
+        })
+        return { name: attr, value }
+    }
+
+    const defaultStr = defaultVal != null ? String(defaultVal) : ''
+    const value = await input({
+        message: desc + (opt.required ? '' : ' (optional)'),
+        default: defaultStr,
+    })
+    if (value === '' && !opt.required) return null
+    return { name: attr, value }
+}
+
+function buildArgv(
+    path: string[],
+    cmd: CommandUnknownOpts,
+    argValues: (string | string[])[],
+    optionValues: Record<string, unknown>,
+): string[] {
+    const argv: string[] = [...path]
+
+    const positionals: string[] = []
+    for (const v of argValues) {
+        if (Array.isArray(v)) positionals.push(...v)
+        else if (v !== '') positionals.push(v)
+    }
+    argv.push(...positionals)
+
+    for (const opt of getVisibleOptions(cmd)) {
+        const attr = opt.attributeName()
+        const val = optionValues[attr]
+        if (val === undefined) continue
+        if (opt.isBoolean()) {
+            if (val === true) {
+                argv.push(opt.long!.startsWith('--') ? opt.long! : `--${opt.long}`)
+            } else if (val === false) {
+                const negateOpt = cmd.options.find((o) => o.negate && o.attributeName() === attr)
+                if (negateOpt?.long) {
+                    argv.push(negateOpt.long.startsWith('--') ? negateOpt.long : `--${negateOpt.long}`)
+                }
+            }
+        } else {
+            if (val !== '' && val != null) {
+                const long = opt.long!.startsWith('--') ? opt.long! : `--${opt.long}`
+                // eslint-disable-next-line @typescript-eslint/no-base-to-string
+                argv.push(long, String(val))
+            }
+        }
+    }
+
+    return argv
+}
+
+export const dummiesCmd = new Command('for-dummies')
+    .alias('interactive')
+    .summary('Interactive menu for all toolkit tasks')
+    .description(
+        'Run a guided flow of menus and prompts to perform any toolkit task. Help and defaults are taken from the command definitions.',
+    )
+    .action(async function (this: CommandUnknownOpts) {
+        const program = this.parent
+        if (!program) {
+            throw new Error('Dummies command must be run under the main program')
+        }
+
+        const { path, cmd } = await chooseCommand(program as CommandUnknownOpts, [])
+
+        if (path.length === 0) {
+            return
+        }
+
+        const args = getVisibleArguments(cmd)
+        const opts = getVisibleOptions(cmd)
+
+        const argValues: (string | string[])[] = []
+        for (const arg of args) {
+            const v = await promptForArgument(arg, argValues.flat(1))
+            argValues.push(v)
+        }
+
+        const optionValues: Record<string, unknown> = {}
+        for (const opt of opts) {
+            const result = await promptForOption(opt)
+            if (result) optionValues[result.name] = result.value
+        }
+
+        const argv = buildArgv(path, cmd, argValues, optionValues)
+        await program.parseAsync(argv, { from: 'user' })
+    })

package/toolkit/generate.ts

@@ -8,6 +8,7 @@ import {
     addAlternativeSolution,
     addMainFile,
     addStatementTranslation,
+    generateStatementFromSolution,
     generateTestCasesGenerator,
 } from '../lib/generate'
 import { newProblem } from '../lib/problem'
@@ -51,8 +52,8 @@ 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')}
+            .map(([key, name]) => `  - ${key}: ${name}`)
+            .join('\n')}
 
 The added translations will be saved in the problem directory overwrite possible existing files.`,
     )
@@ -71,6 +72,31 @@ The added translations will be saved in the problem directory overwrite possible
         })
     })
 
+generateCmd
+    .command('statement')
+    .summary('Generate a statement from a solution using JutgeAI')
+    .description(
+        `Generate a problem statement from a solution using JutgeAI
+
+Use this command to create a statement file from an existing solution.
+The AI infers the problem (input/output, task) from the solution code and writes a problem statement.
+
+Provide the programming language of the solution to use and the target language for the statement.
+An optional prompt can guide the statement generation (e.g. "Focus on edge cases" or "Assume the problem is for beginners").
+
+The result is written to statement.<lang>.tex in the problem directory.`,
+    )
+    .addArgument(new Argument('<proglang>', 'solution to use (e.g. cc, py)').choices(proglangKeys))
+    .addArgument(new Argument('<language>', 'statement language').choices(languageKeys))
+    .option('-d, --directory <path>', 'problem directory', '.')
+    .option('-m, --model <model>', 'AI model to use', settings.defaultModel)
+    .argument('[prompt]', 'optional prompt to guide statement generation', '')
+    .action(async (proglang, language, prompt, { directory, model }) => {
+        const jutge = await getLoggedInJutgeClient()
+        const problem = await newProblem(directory)
+        await generateStatementFromSolution(jutge, model, problem, proglang, language, (prompt ?? '').trim() || undefined)
+    })
+
 generateCmd
     .command('solutions')
     .summary('Generate alternative solutions using JutgeAI')
@@ -82,8 +108,8 @@ 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')}
+            .map(([key, name]) => `  - ${key}: ${name}`)
+            .join('\n')}
 
 The added solutions will be saved in the problem directory overwrite possible existing files.`,
     )
@@ -117,8 +143,8 @@ The main file for the golden solution will be used as a reference for generating
 
 Provide one or more target programming languages from the following list:
 ${Object.entries(languageNames)
-    .map(([key, name]) => `  - ${key}: ${name}`)
-    .join('\n')}
+            .map(([key, name]) => `  - ${key}: ${name}`)
+            .join('\n')}
 
 The added main files will be saved in the problem directory overwrite possible existing files.`,
     )

package/toolkit/index.ts

@@ -11,6 +11,7 @@ import { cleanCmd } from './clean'
 import { compilersCmd } from './compilers'
 import { configCmd } from './config'
 import { cloneCmd } from './clone'
+import { downloadCmd } from './download'
 import { doctorCmd } from './doctor'
 import { generateCmd } from './generate'
 import { makeCmd } from './make'
@@ -24,6 +25,7 @@ import { convertCmd } from './convert'
 import { stageCmd } from './stage'
 import { lintCmd } from './lint'
 import { completeInternalCmd, completionCmd } from './completion'
+import { dummiesCmd } from './dummies'
 
 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)
@@ -37,6 +39,7 @@ program.addCommand(uploadCmd)
 program.addCommand(cmdShare)
 program.addCommand(cleanCmd)
 program.addCommand(cloneCmd)
+program.addCommand(downloadCmd)
 program.addCommand(generateCmd)
 program.addCommand(verifyCmd)
 program.addCommand(lintCmd)
@@ -54,6 +57,7 @@ program.addCommand(completionCmd)
 program.addCommand(aboutCmd)
 program.addCommand(askCmd)
 program.addCommand(completeInternalCmd, { hidden: true })
+program.addCommand(dummiesCmd)
 
 try {
     await program.parseAsync()

package/toolkit/lint.ts

@@ -47,19 +47,17 @@ export async function printLintResults(results: LintResult[], directories: strin
 export const lintCmd = new Command('lint')
     .summary('Lint a problem directory')
 
-    .argument('[directories...]', 'problem directories to lint (default: current directory)')
-    .option('-d, --directory <path>', 'problem directory when no arguments given', '.')
+    .argument('[directory]', 'problem directory to lint', '.')
 
-    .action(async (directories: string[], { directory }) => {
-        const dirs = directories.length > 0 ? directories : [directory]
-        const results = await lintDirectories(dirs)
+    .action(async (directory: string) => {
+        const results = await lintDirectories([directory])
 
         if (results.length === 0) {
             tui.warning('No problem directories found (looked for handler.yml in the given path(s)).')
             return
         }
 
-        const { hasError } = await printLintResults(results, dirs)
+        const { hasError } = await printLintResults(results, [directory])
         if (hasError) {
             process.exitCode = 1
         }

package/toolkit/make.ts

@@ -16,13 +16,13 @@ export const makeCmd = new Command('make')
     .description('Make problem')
 
     .argument('[tasks...]', 'tasks to make: all|info|exe|cor|pdf|txt|md|html', ['all'])
-    .option('-d, --directories <directories...>', 'problem directories', ['.'])
+    .option('-d, --directory <directory>', 'problem directory', '.')
     .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)
     .option('-p, --problem_nm <problem_nm>', 'problem nm', 'DRAFT')
     .option('-w, --watch', 'watch for changes and rebuild incrementally (under development)', false)
 
-    .action(async (tasks, { directories, ignoreErrors, onlyErrors, problem_nm, watch }) => {
+    .action(async (tasks, { directory, ignoreErrors, onlyErrors, problem_nm, watch }) => {
         if (watch) {
             tasks = ['all']
         }
@@ -41,7 +41,7 @@ export const makeCmd = new Command('make')
 
         const errors: Record<string, string> = {} // directory -> error message
 
-        const realDirectories = await findRealDirectories(directories)
+        const realDirectories = await findRealDirectories([directory])
 
         if (watch && realDirectories.length > 1) {
             tui.warning('With --watch only the first directory is watched')

package/toolkit/quiz.ts

@@ -15,10 +15,10 @@ quizCmd
     .command('validate')
     .description('Validate a quiz problem')
 
-    .option('-d, --directories <directories...>', 'problem directories', ['.'])
+    .option('-d, --directory <directory>', 'problem directory', '.')
 
-    .action(async ({ directories }) => {
-        const realDirectories = await findRealDirectories(directories)
+    .action(async ({ directory }) => {
+        const realDirectories = await findRealDirectories([directory])
         for (const directory of realDirectories) {
             await tui.section(`Validating quiz in directory ${tui.hyperlink(directory)}`, async () => {
                 await validateQuiz(directory)

package/toolkit/share.ts

@@ -31,17 +31,17 @@ Finally, it updates problem.yml file with the current sharing settings and shows
     .action(async function () {
         const opts = this.opts()
 
-        let passcode: string | false | undefined
-        if (this.getOptionValueSource('passcode') !== 'default') {
-            const raw = opts.passcode
-            if (raw === false) {
-                passcode = false
-            } else if (raw === true || raw === undefined || raw === '') {
+        let passcode: string | undefined | false
+        if (this.getOptionValueSource('passcode') === undefined) {
+            passcode = undefined
+        } else if (this.getOptionValueSource('passcode') === 'cli') {
+            if (opts.passcode === true) {
                 passcode = await password({ message: 'Passcode:' })
             } else {
-                passcode = raw
+                passcode = opts.passcode
             }
         }
+
         const testcases = this.getOptionValueSource('testcases') !== 'default' ? opts.testcases : undefined
         const solutions = this.getOptionValueSource('solutions') !== 'default' ? opts.solutions : undefined
 

package/docs/windows.md

@@ -1,106 +0,0 @@
-# Notes for Windows
-
-## Installation
-
-- Use PowerShell as terminal. Remember to reopen the terminal after the installation of each tool.
-
-- Bun is a JavaScript runtime like Node.js but faster and lighter.
-  It is required to run the toolkit on Windows. Install `bun` from https://bun.sh/. It is easy.
-
-- Install the toolkit using `bun`:
-
-    ```sh
-    bun install --global "@jutge.org/toolkit"
-    ```
-
-    The first time may take a while as `bun` needs to download and compile some dependencies. If it fails with a `mkdir` error, just try again, it seems to be a transient error.
-
-- Check that the installation was successful:
-
-    ```sh
-    jtk
-    ```
-
-    It should show the help message. You can always add a `--help` flag to any command to get more information.
-
-- Check the tools required by the toolkit:
-
-    ```sh
-    jtk doctor
-    ```
-
-    It should print information about the installed tools. If any tool is missing, consider installing it and try again. Depending on your workflow, some dependencies may not be necessary.
-
-## Upgrade
-
-Try to use the latest version of the toolkit. Upgrade the toolkit to the latest version with the following command:
-
-```powershell
-jtk upgrade
-```
-
-Check the version after upgrading:
-
-```powershell
-jtk --version
-```
-
-## Dependencies
-
-- LaTeX: A LaTeX distribution is required to compile problem statements and get their PDFs. It is not necessary but strongly recommended.
-
-    For Windows, install MiKTeX from https://miktex.org/download. During installation, select the option to install missing packages on-the-fly.
-
-- Pandoc: Pandoc with Lua support is required to convert problem statements to Markdown, Text and HTML. It is not necessary but recommended.
-
-    Install it easily using the Windows Package Manager (`winget`):
-
-    ```powershell
-    winget install --id JohnMacFarlane.Pandoc
-    ```
-
-- Python 3: You only need Python 3 if you plan to use Python scripts in your problems.
-
-    Install Python from https://www.python.org/downloads/windows/. Make sure to check the option to add Python to the system PATH during installation. The toolkit uses `python3` command to run Python scripts.
-
-- C/C++ Compiler: You only need a C/C++ compiler if you plan to use C/C++ programs in your problems. The toolkit uses `gcc` and `g++` commands to compile C and C++ programs, respectively.
-
-    We suggest using [w64devkit](https://github.com/skeeto/w64devkit), a portable C and C++ development kit for Windows. Here are the steps to install it:
-    1. **Download** the latest `.exe` file from https://github.com/skeeto/w64devkit/releases.
-
-    2. **Extract** by double-clicking the downloaded file and choosing a destination (e.g., `C:\w64devkit`).
-
-    3. **Run** `w64devkit.exe` from the extracted folder to open a terminal with gcc and g++ available.
-
-    4. **Test** by typing `gcc --version` in the terminal.
-
-    5. **Compile programs:**
-
-        ```bash
-        gcc myprogram.c -o myprogram.exe
-        g++ myprogram.cpp -o myprogram.exe
-        ```
-
-    Other options are to install [MinGW-w64](http://mingw-w64.org/doku.php) or use the compiler provided by [MSYS2](https://www.msys2.org/).
-
-- Java: You only need Java if you plan to use Java programs in your problems. The toolkit uses the `java` and `javac` commands to run and compile Java programs, respectively.
-
-    Install the Java Runtime Environment (JRE) from https://www.java.com/en/download/manual.jsp. Make sure to download the Windows version.
-
-- Likewise, you may need to install Rust, Haskell and Clojure if you plan to use these languages in your problems. If you know how to install them on Windows, please consider contributing to the documentation.
-
-## Miscellaneous tips
-
-- Open a file with its associated application with `start filename.extension`.
-
-- Show environment variables with `echo $env:VARIABLE`.
-
-- Set environment temporarly variables with `$env:VARIABLE=value`.
-
-- Set environment variables permanently with `[System.Environment]::SetEnvironmentVariable('VARIABLE', 'value', 'User')`.
-
-- Console font doesn't support Unicode: The default console font (Raster Fonts) doesn't support many Unicode characters. Change to a font like "Consolas", "Lucida Console", or "Cascadia Code" in your PowerShell window properties.
-
-```
-
-```