@jutge.org/toolkit 4.3.1 → 4.4.0

package/docs/getting-started-guide.md

@@ -61,6 +61,16 @@ Before we dive into configuration, it's important to know how to get help:
     jtk about
     ```
 
+5. **Enable shell completion (Bash, Zsh, Fish, PowerShell):**
+
+    Completions are available for commands, options, and values (e.g. language codes, compiler ids, template names). To enable them:
+
+    ```bash
+    jtk completion install
+    ```
+
+    After upgrading the toolkit with `jtk upgrade`, run `jtk completion install` again to refresh the completion script.
+
 ### Configuration
 
 Before using the toolkit, you should configure it with your preferences:
@@ -230,6 +240,7 @@ Here's a quick reference of the most commonly used commands:
 jtk --help                          # Show help
 jtk --version                       # Show version
 jtk upgrade                         # Upgrade to latest version
+jtk completion install               # Install/update shell completions
 jtk about                           # Show information about the toolkit
 
 jtk config show                     # Show configuration
@@ -263,7 +274,7 @@ jtk doctor                          # Check system dependencies
 
 ## Tips for Success
 
-1. **Keep the toolkit updated:** Regularly run `jtk upgrade` to get the latest features and fixes.
+1. **Keep the toolkit updated:** Regularly run `jtk upgrade` to get the latest features and fixes. After upgrading, run `jtk completion install` to update shell completions.
 
 2. **Start simple:** Begin with a basic problem and gradually explore more features.
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@jutge.org/toolkit",
     "description": "Toolkit to prepare problems for Jutge.org",
-    "version": "4.3.1",
+    "version": "4.4.0",
     "homepage": "https://jutge.org",
     "author": {
         "name": "Jutge.org",

package/toolkit/completion.ts

@@ -0,0 +1,202 @@
+import { Command } from '@commander-js/extra-typings'
+import { mkdir, readFile, writeFile } from 'fs/promises'
+import { join } from 'path'
+import tui from '../lib/tui'
+import { complete } from '../lib/completion'
+
+/** Hidden command used by completion scripts to get candidates */
+export const completeInternalCmd = new Command('_complete')
+    .description('Internal: output completion candidates (used by shell completion scripts)')
+    .argument('<shell>', 'bash|zsh|fish|powershell')
+    .argument('<cword>', 'index of word being completed', (v) => parseInt(v, 10))
+    .argument('[words...]', 'command line words')
+    .action(async (shell: string, cword: number, words: string[]) => {
+        const result = await complete(words, cword)
+        for (const w of result.words) {
+            process.stdout.write(w + '\n')
+        }
+    })
+
+function bashScript(): string {
+    return `# Bash completion for jtk/jutge-toolkit
+_jtk_completion() {
+    local cur words cword
+    _get_comp_words_by_ref -n : cur words cword
+    local reply
+    reply=($(jtk _complete bash "$cword" -- "\${words[@]}" 2>/dev/null))
+    COMPREPLY=($(compgen -W "\${reply[*]}" -- "$cur"))
+}
+complete -o default -F _jtk_completion jtk jutge-toolkit 2>/dev/null || true
+`
+}
+
+function zshScript(): string {
+    return `# Zsh completion for jtk/jutge-toolkit
+_jtk_completion() {
+    local cword=$((CURRENT - 1))
+    local -a reply
+    reply=("\${(@f)"$(jtk _complete zsh "$cword" -- "\${words[@]}" 2>/dev/null)"}")
+    _describe 'jtk' reply
+}
+compdef _jtk_completion jtk jutge-toolkit
+`
+}
+
+function fishScript(): string {
+    return `# Fish completion for jtk/jutge-toolkit
+function __jtk_completion
+    set -l tokens (commandline -o)
+    set -l cword (math (count $tokens) - 1)
+    jtk _complete fish $cword -- $tokens 2>/dev/null
+end
+complete -c jtk -a '(__jtk_completion)'
+complete -c jutge-toolkit -a '(__jtk_completion)'
+`
+}
+
+function powershellScript(): string {
+    return `# PowerShell completion for jtk/jutge-toolkit
+Register-ArgumentCompleter -CommandName jtk,jutge-toolkit -ScriptBlock {
+    param($wordToComplete, $commandAst, $cursorPosition)
+    $words = $commandAst.CommandElements | ForEach-Object { $_.ToString() }
+    $cword = [Math]::Max(0, $words.Count - 1)
+    $all = $words + $wordToComplete
+    $reply = jtk _complete powershell $cword -- @all 2>$null
+    $reply | Where-Object { $_ -like "$wordToComplete*" }
+}
+`
+}
+
+export const completionCmd = new Command('completion')
+    .description('Generate and install shell completion scripts for jtk')
+    .action(() => {
+        completionCmd.help()
+    })
+
+completionCmd
+    .command('bash')
+    .description('Output Bash completion script')
+    .action(() => {
+        console.log(bashScript())
+    })
+
+completionCmd
+    .command('zsh')
+    .description('Output Zsh completion script')
+    .action(() => {
+        console.log(zshScript())
+    })
+
+completionCmd
+    .command('fish')
+    .description('Output Fish completion script')
+    .action(() => {
+        console.log(fishScript())
+    })
+
+completionCmd
+    .command('powershell')
+    .description('Output PowerShell completion script')
+    .action(() => {
+        console.log(powershellScript())
+    })
+
+completionCmd
+    .command('install [shell]')
+    .description('Install completion script for the current shell (or specify bash|zsh|fish|powershell)')
+    .action(async (shellArg?: string) => {
+        const shell = shellArg || detectShell()
+        const homedir = process.env.HOME || process.env.USERPROFILE || ''
+        if (!homedir) {
+            tui.print('Could not determine home directory (set HOME or USERPROFILE).')
+            return
+        }
+        const xdgData = process.env.XDG_DATA_HOME || join(homedir, '.local', 'share')
+
+        const writeScript = async (filePath: string, script: string): Promise<'created' | 'updated'> => {
+            let existing: string | null = null
+            try {
+                existing = await readFile(filePath, 'utf-8')
+            } catch {
+                // file does not exist
+            }
+            await writeFile(filePath, script, 'utf-8')
+            return existing !== null && existing !== script ? 'updated' : 'created'
+        }
+
+        if (shell === 'bash') {
+            const dir = join(xdgData, 'bash-completion', 'completions')
+            const filePath = join(dir, 'jtk')
+            await mkdir(dir, { recursive: true })
+            const status = await writeScript(filePath, bashScript())
+            tui.success(
+                status === 'created' ? `Created ${tui.hyperlink(filePath)}` : `Updated ${tui.hyperlink(filePath)}`,
+            )
+            tui.print('Restart your shell or run: source "' + filePath + '"')
+        } else if (shell === 'zsh') {
+            const dir = join(homedir, '.zsh')
+            const filePath = join(dir, '_jtk')
+            await mkdir(dir, { recursive: true })
+            const status = await writeScript(filePath, zshScript())
+            tui.success(
+                status === 'created' ? `Created ${tui.hyperlink(filePath)}` : `Updated ${tui.hyperlink(filePath)}`,
+            )
+            const zshrc = join(homedir, '.zshrc')
+            let zshrcContent: string | null = null
+            try {
+                zshrcContent = await readFile(zshrc, 'utf-8')
+            } catch {
+                /* .zshrc may not exist */
+            }
+            const lines: string[] = []
+            if (!zshrcContent?.includes(dir)) {
+                lines.push(`fpath=("${dir}" $fpath)`)
+            }
+            if (!zshrcContent?.includes('compinit')) {
+                lines.push('autoload -Uz compinit && compinit')
+            }
+            if (lines.length > 0) {
+                const toAppend = `\n# jtk completion\n${lines.join('\n')}\n`
+                await writeFile(zshrc, (zshrcContent ?? '') + toAppend, 'utf-8')
+                const added =
+                    lines.length === 2
+                        ? 'fpath and compinit'
+                        : lines.length === 1 && lines[0]!.includes('fpath')
+                          ? 'fpath'
+                          : 'compinit'
+                tui.success(`Updated ${tui.hyperlink(zshrc)} (added ${added})`)
+            }
+            tui.print('Restart your shell to use completions.')
+        } else if (shell === 'fish') {
+            const dir = join(homedir, '.config', 'fish', 'completions')
+            const filePath = join(dir, 'jtk.fish')
+            await mkdir(dir, { recursive: true })
+            const status = await writeScript(filePath, fishScript())
+            tui.success(
+                status === 'created' ? `Created ${tui.hyperlink(filePath)}` : `Updated ${tui.hyperlink(filePath)}`,
+            )
+            tui.print('Restart your shell to use completions.')
+        } else if (shell === 'powershell') {
+            const dir = join(homedir, '.config', 'powershell')
+            await mkdir(dir, { recursive: true })
+            const filePath = join(dir, 'jtk-completion.ps1')
+            const status = await writeScript(filePath, powershellScript())
+            tui.success(
+                status === 'created' ? `Created ${tui.hyperlink(filePath)}` : `Updated ${tui.hyperlink(filePath)}`,
+            )
+            tui.print('Load it in this session: . "' + filePath.replace(/'/g, "''") + '"')
+            tui.print('To load automatically, add the line above to your $PROFILE.')
+        } else {
+            tui.print(`Unknown or unsupported shell: ${shell}`)
+            tui.print('Use: jtk completion install bash|zsh|fish|powershell')
+        }
+    })
+
+function detectShell(): string {
+    const shell = process.env.SHELL || ''
+    if (shell.includes('fish')) return 'fish'
+    if (shell.includes('zsh')) return 'zsh'
+    if (shell.includes('bash')) return 'bash'
+    if (process.env.PSModulePath) return 'powershell'
+    return 'bash'
+}

package/toolkit/generate.ts

@@ -51,8 +51,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.`,
     )
@@ -82,8 +82,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 +117,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.`,
     )
@@ -191,7 +191,6 @@ The new image will be saved as award.png in the problem directory, overriding an
             imagePrompt = 'A colorful award on a white background'
         }
         await tui.section('Generating award image', async () => {
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-call -- generated API client
             const download = await jutge.instructor.jutgeai.createImage({
                 model,
                 label: 'award',

package/toolkit/index.ts

@@ -22,6 +22,8 @@ import { submitCmd } from './submit'
 import { askCmd } from './ask'
 import { convertCmd } from './convert'
 import { stageCmd } from './stage'
+import { lintCmd } from './lint'
+import { completeInternalCmd, completionCmd } from './completion'
 
 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(cleanCmd)
 program.addCommand(cloneCmd)
 program.addCommand(generateCmd)
 program.addCommand(verifyCmd)
+program.addCommand(lintCmd)
 program.addCommand(submitCmd)
 program.addCommand(convertCmd)
 program.addCommand(stageCmd)
@@ -47,12 +50,14 @@ if (settings.developer) {
 }
 program.addCommand(configCmd)
 program.addCommand(upgradeCmd)
+program.addCommand(completionCmd)
 program.addCommand(aboutCmd)
 program.addCommand(askCmd)
+program.addCommand(completeInternalCmd, { hidden: true })
 
 try {
     await program.parseAsync()
-    process.exit(0)
+    process.exit(process.exitCode ?? 0)
 } catch (error) {
     console.log()
     console.error('An error occurred:')

package/toolkit/lint.ts

@@ -0,0 +1,64 @@
+import { Command } from '@commander-js/extra-typings'
+import chalk from 'chalk'
+import { lintDirectories, type LintIssue } from '../lib/lint'
+
+function formatIssue(issue: LintIssue): string {
+    const prefix = issue.severity === 'error' ? chalk.red('error') : chalk.yellow('warning')
+    const path = issue.path ? chalk.gray(` (${issue.path})`) : ''
+    return `  ${prefix} ${issue.code}: ${issue.message}${path}`
+}
+
+export const lintCmd = new Command('lint')
+    .summary('Lint a problem directory')
+    .description(
+        'Check problem.yml/handler.yml schema, required files present, naming conventions, statement structure, sample vs public test consistency, etc.',
+    )
+    .argument('[directories...]', 'problem directories to lint (default: current directory)')
+    .option('-d, --directory <path>', 'problem directory when no arguments given', '.')
+    .action(async (directories: string[], { directory }) => {
+    const dirs = directories.length > 0 ? directories : [directory]
+    const results = await lintDirectories(dirs)
+
+    if (results.length === 0) {
+        console.log(chalk.yellow('No problem directories found (looked for handler.yml in the given path(s)).'))
+        return
+    }
+
+    let hasError = false
+        let hasWarning = false
+
+        for (const result of results) {
+            const errors = result.issues.filter((i) => i.severity === 'error')
+            const warnings = result.issues.filter((i) => i.severity === 'warning')
+            if (errors.length > 0) hasError = true
+            if (warnings.length > 0) hasWarning = true
+
+            const dirLabel = result.directory === dirs[0] && results.length === 1 ? result.directory : result.directory
+            if (result.issues.length === 0) {
+                console.log(chalk.green('✓'), dirLabel, chalk.gray('— no issues'))
+            } else {
+                console.log()
+                console.log(chalk.bold(dirLabel))
+                for (const issue of result.issues) {
+                    console.log(formatIssue(issue))
+                }
+            }
+        }
+
+        if (results.length > 1) {
+            console.log()
+            const totalErrors = results.reduce((s, r) => s + r.issues.filter((i) => i.severity === 'error').length, 0)
+            const totalWarnings = results.reduce((s, r) => s + r.issues.filter((i) => i.severity === 'warning').length, 0)
+            if (totalErrors > 0 || totalWarnings > 0) {
+                console.log(
+                    chalk.gray(
+                        `Total: ${totalErrors} error(s), ${totalWarnings} warning(s) across ${results.length} problem(s)`,
+                    ),
+                )
+            }
+        }
+
+        if (hasError) {
+            process.exitCode = 1
+        }
+    })

package/toolkit/submit.ts

@@ -10,9 +10,10 @@ export const submitCmd = new Command('submit')
     .option('-c, --compiler <id>', 'compiler to use (default: auto-detect from file extension)', 'auto')
     .option('-l, --language <code>', 'language code (ca, es, en, ...)', 'en')
     .option('-n, --no-wait', 'do not wait for submissions to be judged')
+    .option('--no-browser', 'do not open the submission URL in the browser (only print URL and/or wait for verdict in terminal)')
     .option('-a, --annotation <annotation>', "annotation for the submission (default: 'jtk-submit-<nanoid16>')")
 
-    .action(async (programs, { directory, compiler, language, wait, annotation }) => {
+    .action(async (programs, { directory, compiler, language, wait, browser, annotation }) => {
         const annotationValue = annotation ?? `jtk-submit-${nanoid16()}`
-        await submitInDirectory(directory, language, programs, !wait, compiler, annotationValue)
+        await submitInDirectory(directory, language, programs, !wait, browser, compiler, annotationValue)
     })

package/toolkit/ai.ts

@@ -1,56 +0,0 @@
-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)
-    })