@jutge.org/toolkit 4.1.0 → 4.2.1

package/docs/windows.md

@@ -0,0 +1,114 @@
+# 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
+    ```
+
+- Image Magick: ImageMagick is required to process images in problem statements. It is not necessary but recommended.
+
+    Install it easily using the Windows Package Manager (`winget`):
+
+    ```powershell
+    winget install --id ImageMagick.ImageMagick
+    ```
+
+- 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.
+
+```
+
+```

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@jutge.org/toolkit",
     "description": "Toolkit to prepare problems for Jutge.org",
-    "version": "4.1.0",
+    "version": "4.2.1",
     "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,42 @@
+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 }) => {
+        console.log()
+
+        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} in good faith.`)
+    })
+
+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)
+        })
+    })