@learnpack/learnpack 5.0.29 → 5.0.30

package/src/managers/config/index.ts

@@ -1,715 +1,741 @@
-import * as path from "path"
-import * as fs from "fs"
-import * as shell from "shelljs"
-import { exec } from "child_process"
-import { promisify } from "util"
-
-import Console from "../../utils/console"
-import watch from "../../utils/watcher"
-import {
-  ValidationError,
-  NotFoundError,
-  InternalError,
-} from "../../utils/errors"
-
-import defaults from "./defaults"
-import { exercise } from "./exercise"
-
-import { rmSync } from "../file"
-import {
-  IConfigObj,
-  TConfigObjAttributes,
-  TMode,
-  TAgent,
-} from "../../models/config"
-import {
-  IConfigManagerAttributes,
-  IConfigManager,
-} from "../../models/config-manager"
-import { IFile } from "../../models/file"
-
-/* exercise folder name standard */
-const execAsync = promisify(exec)
-
-// eslint-disable-next-line
-const fetch = require("node-fetch")
-// eslint-disable-next-line
-const chalk = require("chalk")
-
-/* exercise folder name standard */
-
-/**
- * Retrieves the configuration path for the learnpack package.
- *
- * @returns An object containing the configuration file path and the base directory.
- * @throws NotFoundError if the learn.json file is not found in the current folder.
- */
-const getConfigPath = () => {
-  const possibleFileNames = ["learn.json", ".learn/learn.json"]
-  const config = possibleFileNames.find(file => fs.existsSync(file)) || null
-  if (config && fs.existsSync(".breathecode"))
-    return { config, base: ".breathecode" }
-  if (config === null)
-    throw NotFoundError(
-      "learn.json file not found on current folder, is this a learnpack package?"
-    )
-  return { config, base: ".learn" }
-}
-
-const getExercisesPath = (base: string) => {
-  const possibleFileNames = ["./exercises", base + "/exercises", "./"]
-  return possibleFileNames.find(file => fs.existsSync(file)) || null
-}
-
-const getGitpodAddress = () => {
-  if (shell.exec("gp -h", { silent: true }).code === 0) {
-    return shell
-      .exec("gp url", { silent: true })
-      .stdout.replace(/(\r\n|\n|\r)/gm, "")
-  }
-
-  Console.debug("Gitpod command line tool not found")
-  return "http://localhost"
-}
-
-const getCodespacesNamespace = () => {
-  // Example: https://orange-rotary-phone-wxpg49q5gcg4rp-3000.app.github.dev
-
-  const codespace_name = shell
-    .exec("echo $CODESPACE_NAME", { silent: true })
-    .stdout.replace(/(\r\n|\n|\r)/gm, "")
-
-  if (
-    !codespace_name ||
-    codespace_name === "" ||
-    codespace_name === undefined ||
-    codespace_name === "$CODESPACE_NAME"
-  ) {
-    return null
-  }
-
-  return codespace_name
-}
-
-export default async ({
-  grading,
-  mode,
-  disableGrading,
-  version,
-}: IConfigManagerAttributes): Promise<IConfigManager> => {
-  const confPath = getConfigPath()
-  Console.debug("This is the config path: ", confPath)
-
-  let configObj: IConfigObj = {}
-
-  if (confPath) {
-    const learnJsonContent = fs.readFileSync(confPath.config)
-    let hiddenBcContent = {}
-
-    if (fs.existsSync(confPath.base + "/config.json")) {
-      hiddenBcContent = fs.readFileSync(confPath.base + "/config.json")
-      hiddenBcContent = JSON.parse(hiddenBcContent as string)
-      if (!hiddenBcContent)
-        throw new Error(
-          `Invalid ${confPath.base}/config.json syntax: Unable to parse.`
-        )
-    }
-
-    const jsonConfig = JSON.parse(`${learnJsonContent}`)
-
-    if (!jsonConfig)
-      throw new Error(`Invalid ${confPath.config} syntax: Unable to parse.`)
-
-    let session: number
-
-    // add using id to the installation
-    if (!jsonConfig.session) {
-      session = Math.floor(Math.random() * 10_000_000_000_000_000_000)
-    } else {
-      session = jsonConfig.session
-      delete jsonConfig.session
-    }
-
-    configObj = deepMerge(hiddenBcContent, {
-      config: jsonConfig,
-      session: session,
-    })
-  } else {
-    throw ValidationError(
-      "No learn.json file has been found, make sure you are in the correct directory. To start a new LearnPack package run: $ learnpack init my-course-name"
-    )
-  }
-
-  configObj = deepMerge(defaults || {}, configObj, {
-    config: {
-      grading: grading || configObj.config?.grading,
-      configPath: confPath.config,
-    },
-  })
-  if (!configObj.config) 
-throw InternalError("Config object not found")
-
-  configObj.config.outputPath = confPath.base + "/dist"
-
-  Console.debug("This is your configuration object: ", {
-    ...configObj,
-    exercises: configObj.exercises ?
-      configObj.exercises.map(e => e.slug) :
-      [],
-  })
-
-  // auto detect agent (if possible)
-  const codespaces_workspace = getCodespacesNamespace()
-  Console.debug("This is the codespace namespace: ", codespaces_workspace)
-
-  if (!configObj.config.editor) {
-    configObj.config.editor = {}
-  }
-
-  Console.debug(
-    "This is the agent, and this should be null an the beginning: ",
-    configObj.config?.editor?.agent
-  )
-
-  if (configObj.config?.editor?.agent) {
-    if (configObj.config.suggestions) {
-      configObj.config.suggestions.agent = configObj.config.editor.agent
-    } else {
-      configObj.config.suggestions = { agent: configObj.config.editor.agent }
-    }
-  }
-
-  if (shell.which("gp") && configObj && configObj.config) {
-    Console.debug("Gitpod detected")
-    configObj.address = getGitpodAddress()
-    configObj.config.publicUrl = `https://${
-      configObj.config.port
-    }-${configObj.address?.slice(8)}`
-    configObj.config.editor.agent = "vscode"
-  } else if (configObj.config && Boolean(codespaces_workspace)) {
-    Console.debug("Codespaces detected: ", codespaces_workspace)
-    configObj.address = `https://${codespaces_workspace}.github.dev`
-    configObj.config.publicUrl = `https://${codespaces_workspace}-${configObj.config.port}.app.github.dev`
-    configObj.config.editor.agent = "vscode"
-  } else {
-    Console.debug("Neither Gitpod nor Codespaces detected, using localhost.")
-    configObj.address = `http://localhost:${configObj.config.port}`
-    configObj.config.publicUrl = `http://localhost:${configObj.config.port}`
-    configObj.config.editor.agent =
-      process.env.TERM_PROGRAM === "vscode" ? "vscode" : "os"
-  }
-
-  if (configObj.config.editor.agent === "vscode" && isCodeCommandAvailable()) {
-    const extensionName = "learn-pack.learnpack-vscode"
-
-    if (!isExtensionInstalled(extensionName)) {
-      Console.info(
-        "The LearnPack extension is not installed, trying to install it automatically."
-      )
-
-      if (!installExtension(extensionName)) {
-        configObj.config.warnings = {
-          extension: EXTENSION_INSTALLATION_STEPS,
-        }
-        Console.warning(
-          "The LearnPack extension is not installed and this tutorial is meant to be run inside VSCode. Please install the LearnPack extension."
-        )
-      }
-    }
-  }
-
-  if (
-    configObj.config.suggestions &&
-    configObj.config.editor &&
-    configObj.config.suggestions.agent !== null &&
-    configObj.config.suggestions.agent !== configObj.config.editor.agent
-  ) {
-    Console.warning(
-      `The suggested agent "${configObj.config.suggestions.agent}" is different from the detected agent "${configObj.config.editor.agent}"`
-    )
-
-    try {
-      configObj.config.warnings = {
-        ...configObj.config.warnings, // Ensure we don't overwrite other warnings
-        agent: buildAgentWarning(
-          configObj.config.editor.agent,
-          configObj.config.suggestions.agent
-        ),
-      }
-    } catch {
-      Console.error("IMPOSSIBLE TO SET WARNING")
-    }
-  }
-
-  if (configObj.config && !configObj.config.publicUrl)
-    configObj.config.publicUrl = `${configObj.address}:${configObj.config.port}`
-
-  if (configObj.config && !configObj.config.editor.mode && mode) {
-    configObj.config.editor.mode = mode as TMode
-  }
-
-  configObj.config.editor.mode =
-    process.env.TERM_PROGRAM === "vscode" ? "extension" : "preview"
-
-  if (version) 
-configObj.config.editor.version = version
-  else if (configObj.config.editor.version === null) {
-    Console.debug("Config version not found, downloading default.")
-    const resp = await fetch(
-      "https://raw.githubusercontent.com/learnpack/ide/master/package.json"
-    )
-    const packageJSON = await resp.json()
-    configObj.config.editor.version = packageJSON.version || "4.0.2"
-  }
-
-  configObj.config.dirPath = "./" + confPath.base
-  configObj.config.exercisesPath = getExercisesPath(confPath.base) || "./"
-
-  if (configObj.config.variables) {
-    const allowedCommands = new Set(["ls", "pwd", "echo", "node", "python"])
-
-    const variableKeys = Object.keys(configObj.config.variables)
-    const promises = []
-
-    for (const v of variableKeys) {
-      if (Object.prototype.hasOwnProperty.call(configObj.config.variables, v)) {
-        const variable = configObj.config.variables[v]
-
-        if (typeof variable === "string") {
-          continue
-        }
-
-        const type = variable.type
-
-        if (type === "command") {
-          const promise = (async () => {
-            try {
-              // Validate the command
-              if (!allowedCommands.has(variable.source.split(" ")[0])) {
-                throw new Error("Command not allowed")
-              }
-
-              // Execute the code and replace the value
-              const { stdout } = await execAsync(variable.source)
-              if (!configObj.config || !configObj.config.variables) 
-return
-
-              configObj.config.variables[v] = stdout.trim()
-            } catch (error) {
-              console.error(`Error executing code: ${error}`)
-            }
-          })()
-          promises.push(promise)
-        } else if (type === "string") {
-          configObj.config.variables[v] = variable.source
-        }
-      }
-    }
-
-    await Promise.all(promises)
-  }
-
-  return {
-    validLanguages: {},
-    get: () => {
-      return configObj
-    },
-    validateEngine: function (language: string, server: any, socket: any) {
-      // eslint-disable-next-line
-      const alias = (_l: string) => {
-        const map: any = {
-          python3: "python",
-        }
-        if (map[_l]) 
-return map[_l]
-        return _l
-      }
-
-      // decode aliases
-      language = alias(language)
-
-      if (this.validLanguages[language]) 
-return true
-
-      Console.debug(`Validating engine for ${language} compilation`)
-      let result = shell.exec("learnpack plugins", { silent: true })
-
-      if (
-        result.code === 0 &&
-        result.stdout.includes(`@learnpack/${language}`)
-      ) {
-        this.validLanguages[language] = true
-        return true
-      }
-
-      Console.info(`Language engine for ${language} not found, installing...`)
-      // Install the compiler in their new versions
-      result = shell.exec(`learnpack plugins:install @learnpack/${language}`, {
-        silent: true,
-      })
-      if (result.code === 0) {
-        socket.log(
-          "compiling",
-          "Installing the python compiler, you will have to reset the exercises after installation by writing on your terminal: $ learnpack run"
-        )
-        Console.info(
-          `Successfully installed the ${language} exercise engine, \n please start learnpack again by running the following command: \n ${chalk.white(
-            "$ learnpack start"
-          )}\n\n `
-        )
-        server.terminate()
-        return false
-      }
-
-      this.validLanguages[language] = false
-      socket.error(`Error installing ${language} exercise engine`)
-      Console.error(`Error installing ${language} exercise engine`)
-      Console.log(result.stdout)
-      throw InternalError(`Error installing ${language} exercise engine`)
-    },
-    logout: () => {
-      if (configObj.config) {
-        rmSync(configObj.config.dirPath + "/.session")
-      }
-    },
-    clean: () => {
-      if (configObj.config) {
-        if (configObj.config.outputPath) {
-          rmSync(configObj.config.outputPath)
-        }
-
-        rmSync(configObj.config.dirPath + "/_app")
-        rmSync(configObj.config.dirPath + "/reports")
-        rmSync(configObj.config.dirPath + "/.session")
-        rmSync(configObj.config.dirPath + "/resets")
-
-        // clean __pycache__ folder
-        rmSync(configObj.config.dirPath + "/../__pycache__")
-
-        // clean the __pycache__ for each exercise it exists
-        if (configObj.exercises) {
-          for (const e of configObj.exercises) {
-            if (fs.existsSync(e.path + "/__pycache__")) {
-              rmSync(e.path + "/__pycache__")
-            }
-          }
-        }
-
-        // clean tag gz
-        if (fs.existsSync(configObj.config.dirPath + "/app.tar.gz"))
-          fs.unlinkSync(configObj.config.dirPath + "/app.tar.gz")
-
-        if (fs.existsSync(configObj.config.dirPath + "/config.json"))
-          fs.unlinkSync(configObj.config.dirPath + "/config.json")
-
-        if (fs.existsSync(configObj.config.dirPath + "/telemetry.json"))
-          fs.unlinkSync(configObj.config.dirPath + "/telemetry.json")
-
-        if (fs.existsSync(configObj.config.dirPath + "/vscode_queue.json"))
-          fs.unlinkSync(configObj.config.dirPath + "/vscode_queue.json")
-      }
-    },
-    getExercise: slug => {
-      Console.debug("ExercisePath Slug", slug)
-      const exercise = (configObj.exercises || []).find(
-        ex => ex.slug === slug
-      )
-      if (!exercise) 
-throw ValidationError(`Exercise ${slug} not found`)
-
-      return exercise
-    },
-    getAllExercises: () => {
-      return configObj.exercises
-    },
-    startExercise: function (slug: string) {
-      const exercise = this.getExercise(slug)
-
-      // set config.json with current exercise
-      configObj.currentExercise = exercise.slug
-
-      this.save()
-
-      // eslint-disable-next-line
-      exercise.files.forEach((f: IFile) => {
-        if (configObj.config) {
-          const _path = configObj.config.outputPath + "/" + f.name
-          if (f.hidden === false && fs.existsSync(_path)) 
-fs.unlinkSync(_path)
-        }
-      })
-
-      return exercise
-    },
-    noCurrentExercise: function () {
-      configObj.currentExercise = null
-      this.save()
-    },
-    reset: slug => {
-      if (
-        configObj.config &&
-        !fs.existsSync(`${configObj.config.dirPath}/resets/` + slug)
-      )
-        throw ValidationError("Could not find the original files for " + slug)
-
-      const exercise = (configObj.exercises || []).find(
-        ex => ex.slug === slug
-      )
-      if (!exercise)
-        throw ValidationError(`Exercise ${slug} not found on the configuration`)
-
-      if (configObj.config) {
-        for (const fileName of fs.readdirSync(
-          `${configObj.config.dirPath}/resets/${slug}/`
-        )) {
-          const content = fs.readFileSync(
-            `${configObj.config?.dirPath}/resets/${slug}/${fileName}`
-          )
-          fs.writeFileSync(`${exercise.path}/${fileName}`, content)
-        }
-      }
-    },
-    buildIndex: function () {
-      Console.info("Building the exercise index...")
-
-      const isDirectory = (source: string) => {
-        const name = path.basename(source)
-        if (name === path.basename(configObj?.config?.dirPath || ""))
-          return false
-        // ignore folders that start with a dot
-        if (name.charAt(0) === "." || name.charAt(0) === "_") 
-return false
-
-        return fs.lstatSync(source).isDirectory()
-      }
-
-      const getDirectories = (source: string) =>
-        fs
-          .readdirSync(source)
-          .map(name => path.join(source, name))
-          .filter(isDirectory)
-      // add the .learn folder
-      if (!fs.existsSync(confPath.base)) 
-fs.mkdirSync(confPath.base)
-      // add the outout folder where webpack will publish the the html/css/js files
-      if (
-        configObj.config &&
-        configObj.config.outputPath &&
-        !fs.existsSync(configObj.config.outputPath)
-      )
-        fs.mkdirSync(configObj.config.outputPath)
-
-      // TODO: we could use npm library front-mater to read the title of the exercises from the README.md
-      const grupedByDirectory = getDirectories(
-        configObj?.config?.exercisesPath || ""
-      )
-      configObj.exercises =
-        grupedByDirectory.length > 0 ?
-          grupedByDirectory.map((path, position) =>
-              exercise(path, position, configObj)
-            ) :
-          [exercise(configObj?.config?.exercisesPath || "", 0, configObj)]
-      this.save()
-    },
-    watchIndex: function (onChange: (filename: string) => void) {
-      if (configObj.config && !configObj.config.exercisesPath)
-        throw ValidationError(
-          "No exercises directory to watch: " + configObj.config.exercisesPath
-        )
-
-      this.buildIndex()
-
-      watch(configObj?.config?.exercisesPath || "", onChange)
-        .then(() => {
-          Console.debug("Changes detected on your exercises")
-          this.buildIndex()
-          // if (onChange) onChange(filename);
-        })
-        .catch(error => {
-          throw error
-        })
-    },
-
-    save: () => {
-      Console.debug("Saving configuration with: ", configObj)
-      // remove the duplicates form the actions array
-      // configObj.config.actions = [...new Set(configObj.config.actions)];
-      if (configObj.config) {
-        configObj.config.translations = [
-          ...new Set(configObj.config.translations),
-        ]
-        fs.writeFileSync(
-          configObj.config.dirPath + "/config.json",
-          JSON.stringify(configObj, null, 4)
-        )
-      }
-    },
-  } as IConfigManager
-}
-
-function deepMerge(...sources: any): any {
-  let acc: any = {}
-  for (const source of sources) {
-    if (Array.isArray(source)) {
-      if (!Array.isArray(acc)) {
-        acc = []
-      }
-
-      acc = [...source]
-    } else if (source instanceof Object) {
-      // eslint-disable-next-line
-      for (let [key, value] of Object.entries(source)) {
-        if (value instanceof Object && key in acc) {
-          value = deepMerge(acc[key], value)
-        }
-
-        if (value !== undefined) 
-acc = { ...acc, [key]: value }
-      }
-    }
-  }
-
-  return acc
-}
-
-const buildAgentWarning = (current: TAgent, suggested: TAgent): string => {
-  const message = `# Agent mismatch!\n
-        
-In LearnPack, the agent is in charge of running the LearnPack interface.
-
-You're currently using LearnPack through \`${current}\` but the suggested agent is \`${suggested}\`. 
-
-We recommend strongly recommend changing your agent.
-
-  ${stepsToChangeAgent(suggested)}
-       `
-
-  return message
-}
-
-const stepsToChangeAgent = (agent: TAgent): string => {
-  if (agent === "vscode") {
-    return `
-# Steps to Change Agent to VSCode
-
-1. **Install VSCode**:
-   - Visit the [VSCode website](https://code.visualstudio.com/Download) and download the latest version.
-   - Follow the installation instructions for your operating system.
-
-2. **Install LearnPack VSCode Extension**:
-   - Open VSCode.
-   - Go to the Extensions view by clicking on the Extensions icon in the Activity Bar on the side of the window or by pressing \`Ctrl+Shift+X\`.
-   - Search for "LearnPack" and click "Install".
-   - If the extension is already installed but disabled, enable it.
-
-3. **Run LearnPack in VSCode**:
-   - Open your terminal in VSCode.
-   - Navigate to your LearnPack project directory.
-   - Run the following command:
-     \`\`\`sh
-     learnpack start
-     \`\`\`
-
-We strongly recommend using VSCode for a better learning experience.
-    `
-  }
-
-  if (agent === "os") {
-    return `
-# Steps to Change Agent to OS
-
-This learning package was designed to run outside of VSCode. We strongly recommend closing VSCode and running the package independently.
-
-1. **Close VSCode**:
-   - Save your work and close the VSCode application.
-
-2. **Open a New Terminal**:
-   - Open a terminal or command prompt on your operating system.
-
-3. **Navigate to Your LearnPack Project Directory**:
-   - Use the \`cd\` command to navigate to the directory where your LearnPack project is located.
-
-4. **Run LearnPack**:
-   - Run the following command to start LearnPack:
-     \`\`\`sh
-     learnpack start
-     \`\`\`
-
-We strongly recommend running the package independently for a better learning experience.
-    `
-  }
-
-  return ""
-}
-
-/**
- * Checks if the 'code' command is available in the terminal.
- *
- * @returns {boolean} True if the 'code' command is available, false otherwise.
- */
-const isCodeCommandAvailable = (): boolean => {
-  return shell.which("code") !== null
-}
-
-/**
- * Checks if a specific VSCode extension is installed.
- *
- * @param {string} extensionName - The name of the extension to check.
- * @returns {boolean} True if the extension is installed, false otherwise.
- */
-const isExtensionInstalled = (extensionName: string): boolean => {
-  if (!isCodeCommandAvailable()) {
-    throw new Error(
-      "The 'code' command is not available in the terminal. Please ensure that VSCode is installed and the 'code' command is added to your PATH."
-    )
-  }
-
-  const result = shell.exec("code --list-extensions", { silent: true })
-  return result.stdout.split("\n").includes(extensionName)
-}
-
-const EXTENSION_INSTALLATION_STEPS = `
-# Steps to Install LearnPack VSCode Extension
-
-1. **Open VSCode**:
-   - Launch the Visual Studio Code application on your computer.
-
-2. **Go to Extensions View**:
-   - Click on the Extensions icon in the Activity Bar on the side of the window.
-   - Alternatively, you can open the Extensions view by pressing \`Ctrl+Shift+X\`.
-
-3. **Search for LearnPack**:
-   - In the Extensions view, type "LearnPack" into the search bar.
-
-4. **Install the Extension**:
-   - Find the "LearnPack" extension in the search results and click the "Install" button.
-   - If the extension is already installed but disabled, click the "Enable" button.
-
-5. **Verify Installation**:
-   - Once installed, you can verify the installation by running the following command in the terminal:
-     \`\`\`sh
-     code --list-extensions | grep learn-pack.learnpack-vscode
-     \`\`\`
-   - If the extension is listed, it means the installation was successful.
-
-We strongly recommend using the LearnPack extension in VSCode for a better learning experience.
-`
-
-/**
- * Installs the LearnPack VSCode extension if the 'code' command is available.
- *
- * @param {string} extensionName - The name of the extension to install.
- * @returns {boolean} True if the installation was successful, false otherwise.
- */
-const installExtension = (extensionName: string): boolean => {
-  if (!isCodeCommandAvailable()) {
-    throw new Error(
-      "The 'code' command is not available in the terminal. Please ensure that VSCode is installed and the 'code' command is added to your PATH."
-    )
-  }
-
-  const result = shell.exec(`code --install-extension ${extensionName}`, {
-    silent: true,
-  })
-  return result.code === 0
-}
+import * as path from "path"
+import * as fs from "fs"
+import * as shell from "shelljs"
+import { exec } from "child_process"
+import { promisify } from "util"
+
+import Console from "../../utils/console"
+import watch from "../../utils/watcher"
+import {
+  ValidationError,
+  NotFoundError,
+  InternalError,
+} from "../../utils/errors"
+
+import defaults from "./defaults"
+import { exercise } from "./exercise"
+
+import { rmSync } from "../file"
+import {
+  IConfigObj,
+  TConfigObjAttributes,
+  TMode,
+  TAgent,
+} from "../../models/config"
+import {
+  IConfigManagerAttributes,
+  IConfigManager,
+} from "../../models/config-manager"
+import { IFile } from "../../models/file"
+
+/* exercise folder name standard */
+const execAsync = promisify(exec)
+
+// eslint-disable-next-line
+const fetch = require("node-fetch")
+// eslint-disable-next-line
+const chalk = require("chalk")
+
+/* exercise folder name standard */
+
+/**
+ * Retrieves the configuration path for the learnpack package.
+ *
+ * @returns An object containing the configuration file path and the base directory.
+ * @throws NotFoundError if the learn.json file is not found in the current folder.
+ */
+const getConfigPath = () => {
+  const possibleFileNames = ["learn.json", ".learn/learn.json"]
+  const config = possibleFileNames.find(file => fs.existsSync(file)) || null
+  if (config && fs.existsSync(".breathecode"))
+    return { config, base: ".breathecode" }
+  if (config === null)
+    throw NotFoundError(
+      "learn.json file not found on current folder, is this a learnpack package?"
+    )
+  return { config, base: ".learn" }
+}
+
+const getExercisesPath = (base: string) => {
+  const possibleFileNames = ["./exercises", base + "/exercises", "./"]
+  return possibleFileNames.find(file => fs.existsSync(file)) || null
+}
+
+const getGitpodAddress = () => {
+  if (shell.exec("gp -h", { silent: true }).code === 0) {
+    return shell
+      .exec("gp url", { silent: true })
+      .stdout.replace(/(\r\n|\n|\r)/gm, "")
+  }
+
+  Console.debug("Gitpod command line tool not found")
+  return "http://localhost"
+}
+
+const getCodespacesNamespace = () => {
+  // Example: https://orange-rotary-phone-wxpg49q5gcg4rp-3000.app.github.dev
+
+  const codespace_name = shell
+    .exec("echo $CODESPACE_NAME", { silent: true })
+    .stdout.replace(/(\r\n|\n|\r)/gm, "")
+
+  if (
+    !codespace_name ||
+    codespace_name === "" ||
+    codespace_name === undefined ||
+    codespace_name === "$CODESPACE_NAME"
+  ) {
+    return null
+  }
+
+  return codespace_name
+}
+
+export default async ({
+  grading,
+  mode,
+  disableGrading,
+  version,
+}: IConfigManagerAttributes): Promise<IConfigManager> => {
+  const confPath = getConfigPath()
+  Console.debug("This is the config path: ", confPath)
+
+  let configObj: IConfigObj = {}
+
+  if (confPath) {
+    const learnJsonContent = fs.readFileSync(confPath.config)
+    let hiddenBcContent = {}
+
+    if (fs.existsSync(confPath.base + "/config.json")) {
+      hiddenBcContent = fs.readFileSync(confPath.base + "/config.json")
+      hiddenBcContent = JSON.parse(hiddenBcContent as string)
+      if (!hiddenBcContent)
+        throw new Error(
+          `Invalid ${confPath.base}/config.json syntax: Unable to parse.`
+        )
+    }
+
+    const jsonConfig = JSON.parse(`${learnJsonContent}`)
+
+    if (!jsonConfig)
+      throw new Error(`Invalid ${confPath.config} syntax: Unable to parse.`)
+
+    let session: number
+
+    // add using id to the installation
+    if (!jsonConfig.session) {
+      session = Math.floor(Math.random() * 10_000_000_000_000_000_000)
+    } else {
+      session = jsonConfig.session
+      delete jsonConfig.session
+    }
+
+    configObj = deepMerge(hiddenBcContent, {
+      config: jsonConfig,
+      session: session,
+    })
+  } else {
+    throw ValidationError(
+      "No learn.json file has been found, make sure you are in the correct directory. To start a new LearnPack package run: $ learnpack init my-course-name"
+    )
+  }
+
+  configObj = deepMerge(defaults || {}, configObj, {
+    config: {
+      grading: grading || configObj.config?.grading,
+      configPath: confPath.config,
+    },
+  })
+  if (!configObj.config) 
+throw InternalError("Config object not found")
+
+  configObj.config.outputPath = confPath.base + "/dist"
+
+  Console.debug("This is your configuration object: ", {
+    ...configObj,
+    exercises: configObj.exercises ?
+      configObj.exercises.map(e => e.slug) :
+      [],
+  })
+
+  // auto detect agent (if possible)
+  const codespaces_workspace = getCodespacesNamespace()
+  Console.debug("This is the codespace namespace: ", codespaces_workspace)
+
+  if (!configObj.config.editor) {
+    configObj.config.editor = {}
+  }
+
+  Console.debug(
+    "This is the agent, and this should be null an the beginning: ",
+    configObj.config?.editor?.agent
+  )
+
+  if (configObj.config?.editor?.agent) {
+    if (configObj.config.suggestions) {
+      configObj.config.suggestions.agent = configObj.config.editor.agent
+    } else {
+      configObj.config.suggestions = { agent: configObj.config.editor.agent }
+    }
+  }
+
+  if (shell.which("gp") && configObj && configObj.config) {
+    Console.debug("Gitpod detected")
+    configObj.address = getGitpodAddress()
+    configObj.config.publicUrl = `https://${
+      configObj.config.port
+    }-${configObj.address?.slice(8)}`
+    configObj.config.editor.agent = "vscode"
+  } else if (configObj.config && Boolean(codespaces_workspace)) {
+    Console.debug("Codespaces detected: ", codespaces_workspace)
+    configObj.address = `https://${codespaces_workspace}.github.dev`
+    configObj.config.publicUrl = `https://${codespaces_workspace}-${configObj.config.port}.app.github.dev`
+    configObj.config.editor.agent = "vscode"
+  } else {
+    Console.debug("Neither Gitpod nor Codespaces detected, using localhost.")
+    configObj.address = `http://localhost:${configObj.config.port}`
+    configObj.config.publicUrl = `http://localhost:${configObj.config.port}`
+    configObj.config.editor.agent =
+      process.env.TERM_PROGRAM === "vscode" ? "vscode" : "os"
+  }
+
+  if (configObj.config.editor.agent === "vscode" && isCodeCommandAvailable()) {
+    const extensionName = "learn-pack.learnpack-vscode"
+
+    if (!isExtensionInstalled(extensionName)) {
+      Console.info(
+        "The LearnPack extension is not installed, trying to install it automatically."
+      )
+
+      if (!installExtension(extensionName)) {
+        configObj.config.warnings = {
+          extension: EXTENSION_INSTALLATION_STEPS,
+        }
+        Console.warning(
+          "The LearnPack extension is not installed and this tutorial is meant to be run inside VSCode. Please install the LearnPack extension."
+        )
+      }
+    }
+  }
+
+  if (
+    configObj.config.suggestions &&
+    configObj.config.editor &&
+    configObj.config.suggestions.agent !== null &&
+    configObj.config.suggestions.agent !== configObj.config.editor.agent
+  ) {
+    Console.warning(
+      `The suggested agent "${configObj.config.suggestions.agent}" is different from the detected agent "${configObj.config.editor.agent}"`
+    )
+
+    try {
+      configObj.config.warnings = {
+        ...configObj.config.warnings, // Ensure we don't overwrite other warnings
+        agent: buildAgentWarning(
+          configObj.config.editor.agent,
+          configObj.config.suggestions.agent
+        ),
+      }
+    } catch {
+      Console.error("IMPOSSIBLE TO SET WARNING")
+    }
+  }
+
+  if (configObj.config && !configObj.config.publicUrl)
+    configObj.config.publicUrl = `${configObj.address}:${configObj.config.port}`
+
+  if (configObj.config && !configObj.config.editor.mode && mode) {
+    configObj.config.editor.mode = mode as TMode
+  }
+
+  configObj.config.editor.mode =
+    process.env.TERM_PROGRAM === "vscode" ? "extension" : "preview"
+
+  if (version) 
+configObj.config.editor.version = version
+  else if (configObj.config.editor.version === null) {
+    Console.debug("Config version not found, downloading default.")
+    const resp = await fetch(
+      "https://raw.githubusercontent.com/learnpack/ide/master/package.json"
+    )
+    const packageJSON = await resp.json()
+    configObj.config.editor.version = packageJSON.version || "4.0.2"
+  }
+
+  configObj.config.dirPath = "./" + confPath.base
+  configObj.config.exercisesPath = getExercisesPath(confPath.base) || "./"
+
+  if (configObj.config.variables) {
+    const allowedCommands = new Set(["ls", "pwd", "echo", "node", "python"])
+
+    const variableKeys = Object.keys(configObj.config.variables)
+    const promises = []
+
+    for (const v of variableKeys) {
+      if (Object.prototype.hasOwnProperty.call(configObj.config.variables, v)) {
+        const variable = configObj.config.variables[v]
+
+        if (typeof variable === "string") {
+          continue
+        }
+
+        const type = variable.type
+
+        if (type === "command") {
+          const promise = (async () => {
+            try {
+              // Validate the command
+              if (!allowedCommands.has(variable.source.split(" ")[0])) {
+                throw new Error("Command not allowed")
+              }
+
+              // Execute the code and replace the value
+              const { stdout } = await execAsync(variable.source)
+              if (!configObj.config || !configObj.config.variables) 
+return
+
+              configObj.config.variables[v] = stdout.trim()
+            } catch (error) {
+              console.error(`Error executing code: ${error}`)
+            }
+          })()
+          promises.push(promise)
+        } else if (type === "string") {
+          configObj.config.variables[v] = variable.source
+        }
+      }
+    }
+
+    await Promise.all(promises)
+  }
+
+  return {
+    validLanguages: {},
+    get: () => {
+      return configObj
+    },
+    validateEngine: function (language: string, server: any, socket: any) {
+      // eslint-disable-next-line
+      const alias = (_l: string) => {
+        const map: any = {
+          python3: "python",
+        }
+        if (map[_l]) 
+return map[_l]
+        return _l
+      }
+
+      // decode aliases
+      language = alias(language)
+
+      if (this.validLanguages[language]) 
+return true
+
+      Console.debug(`Validating engine for ${language} compilation`)
+      let result = shell.exec("learnpack plugins", { silent: true })
+
+      if (
+        result.code === 0 &&
+        result.stdout.includes(`@learnpack/${language}`)
+      ) {
+        this.validLanguages[language] = true
+        return true
+      }
+
+      Console.info(`Language engine for ${language} not found, installing...`)
+      // Install the compiler in their new versions
+      result = shell.exec(`learnpack plugins:install @learnpack/${language}`, {
+        silent: true,
+      })
+      if (result.code === 0) {
+        socket.log(
+          "compiling",
+          "Installing the python compiler, you will have to reset the exercises after installation by writing on your terminal: $ learnpack run"
+        )
+        Console.info(
+          `Successfully installed the ${language} exercise engine, \n please start learnpack again by running the following command: \n ${chalk.white(
+            "$ learnpack start"
+          )}\n\n `
+        )
+        server.terminate()
+        return false
+      }
+
+      this.validLanguages[language] = false
+      socket.error(`Error installing ${language} exercise engine`)
+      Console.error(`Error installing ${language} exercise engine`)
+      Console.log(result.stdout)
+      throw InternalError(`Error installing ${language} exercise engine`)
+    },
+    logout: () => {
+      if (configObj.config) {
+        rmSync(configObj.config.dirPath + "/.session")
+      }
+    },
+    clean: () => {
+      if (configObj.config) {
+        if (configObj.config.outputPath) {
+          rmSync(configObj.config.outputPath)
+        }
+
+        rmSync(configObj.config.dirPath + "/_app")
+        rmSync(configObj.config.dirPath + "/reports")
+        rmSync(configObj.config.dirPath + "/.session")
+        rmSync(configObj.config.dirPath + "/resets")
+
+        // clean __pycache__ folder
+        rmSync(configObj.config.dirPath + "/../__pycache__")
+
+        // clean the __pycache__ for each exercise it exists
+        if (configObj.exercises) {
+          for (const e of configObj.exercises) {
+            if (fs.existsSync(e.path + "/__pycache__")) {
+              rmSync(e.path + "/__pycache__")
+            }
+          }
+        }
+
+        // clean tag gz
+        if (fs.existsSync(configObj.config.dirPath + "/app.tar.gz"))
+          fs.unlinkSync(configObj.config.dirPath + "/app.tar.gz")
+
+        if (fs.existsSync(configObj.config.dirPath + "/config.json"))
+          fs.unlinkSync(configObj.config.dirPath + "/config.json")
+
+        if (fs.existsSync(configObj.config.dirPath + "/telemetry.json"))
+          fs.unlinkSync(configObj.config.dirPath + "/telemetry.json")
+
+        if (fs.existsSync(configObj.config.dirPath + "/vscode_queue.json"))
+          fs.unlinkSync(configObj.config.dirPath + "/vscode_queue.json")
+      }
+    },
+    getExercise: slug => {
+      Console.debug("ExercisePath Slug", slug)
+      const exercise = (configObj.exercises || []).find(
+        ex => ex.slug === slug
+      )
+      if (!exercise) 
+throw ValidationError(`Exercise ${slug} not found`)
+
+      return exercise
+    },
+    getAllExercises: () => {
+      return configObj.exercises
+    },
+    startExercise: function (slug: string) {
+      const exercise = this.getExercise(slug)
+
+      // set config.json with current exercise
+      configObj.currentExercise = exercise.slug
+
+      this.save()
+
+      // eslint-disable-next-line
+      exercise.files.forEach((f: IFile) => {
+        if (configObj.config) {
+          const _path = configObj.config.outputPath + "/" + f.name
+          if (f.hidden === false && fs.existsSync(_path)) 
+fs.unlinkSync(_path)
+        }
+      })
+
+      return exercise
+    },
+    noCurrentExercise: function () {
+      configObj.currentExercise = null
+      this.save()
+    },
+    reset: slug => {
+      if (
+        configObj.config &&
+        !fs.existsSync(`${configObj.config.dirPath}/resets/` + slug)
+      )
+        throw ValidationError("Could not find the original files for " + slug)
+
+      const exercise = (configObj.exercises || []).find(
+        ex => ex.slug === slug
+      )
+      if (!exercise)
+        throw ValidationError(`Exercise ${slug} not found on the configuration`)
+
+      if (configObj.config) {
+        for (const fileName of fs.readdirSync(
+          `${configObj.config.dirPath}/resets/${slug}/`
+        )) {
+          const content = fs.readFileSync(
+            `${configObj.config?.dirPath}/resets/${slug}/${fileName}`
+          )
+          fs.writeFileSync(`${exercise.path}/${fileName}`, content)
+        }
+      }
+    },
+
+    buildIndex: function () {
+      Console.info("Building the exercise index...")
+
+      const isDirectory = (source: string) => {
+        const name = path.basename(source)
+        if (name === path.basename(configObj?.config?.dirPath || ""))
+          return false
+        // ignore folders that start with a dot
+        if (name.charAt(0) === "." || name.charAt(0) === "_") 
+return false
+
+        return fs.lstatSync(source).isDirectory()
+      }
+
+      const getDirectories = (source: string) =>
+        fs
+          .readdirSync(source)
+          .map(name => path.join(source, name))
+          .filter(isDirectory)
+      // add the .learn folder
+      if (!fs.existsSync(confPath.base)) 
+fs.mkdirSync(confPath.base)
+      // add the outout folder where webpack will publish the the html/css/js files
+      if (
+        configObj.config &&
+        configObj.config.outputPath &&
+        !fs.existsSync(configObj.config.outputPath)
+      )
+        fs.mkdirSync(configObj.config.outputPath)
+
+      // TODO: we could use npm library front-mater to read the title of the exercises from the README.md
+      const grupedByDirectory = getDirectories(
+        configObj?.config?.exercisesPath || ""
+      )
+      configObj.exercises =
+        grupedByDirectory.length > 0 ?
+          grupedByDirectory.map((path, position) =>
+              exercise(path, position, configObj)
+            ) :
+          [exercise(configObj?.config?.exercisesPath || "", 0, configObj)]
+      this.save()
+    },
+    createExercise: (slug: string, content: string, language: string) => {
+      try {
+        const dirPath = `${configObj.config?.exercisesPath}/${slug}`
+        if (!fs.existsSync(dirPath)) 
+fs.mkdirSync(dirPath, { recursive: true })
+        const isEnglish = language === "us" || language === "en"
+        const fileName = isEnglish ? "README.md" : `README.${language}.md`
+        fs.writeFileSync(`${dirPath}/${fileName}`, content)
+
+        return true
+      } catch (error) {
+        Console.error("Error creating exercise: ", error)
+        return false
+      }
+    },
+
+    deleteExercise: (slug: string) => {
+      const dirPath = `${configObj.config?.exercisesPath}/${slug}`
+      if (fs.existsSync(dirPath)) {
+        fs.rmSync(dirPath, { recursive: true, force: true })
+        return true
+      }
+
+      return false
+    },
+    watchIndex: function (onChange: (filename: string) => void) {
+      if (configObj.config && !configObj.config.exercisesPath)
+        throw ValidationError(
+          "No exercises directory to watch: " + configObj.config.exercisesPath
+        )
+
+      this.buildIndex()
+
+      watch(configObj?.config?.exercisesPath || "", onChange)
+        .then(() => {
+          Console.debug("Changes detected on your exercises")
+          this.buildIndex()
+          // if (onChange) onChange(filename);
+        })
+        .catch(error => {
+          throw error
+        })
+    },
+
+    save: () => {
+      Console.debug("Saving configuration with: ", configObj)
+      // remove the duplicates form the actions array
+      // configObj.config.actions = [...new Set(configObj.config.actions)];
+      if (configObj.config) {
+        configObj.config.translations = [
+          ...new Set(configObj.config.translations),
+        ]
+        fs.writeFileSync(
+          configObj.config.dirPath + "/config.json",
+          JSON.stringify(configObj, null, 4)
+        )
+      }
+    },
+  } as IConfigManager
+}
+
+function deepMerge(...sources: any): any {
+  let acc: any = {}
+  for (const source of sources) {
+    if (Array.isArray(source)) {
+      if (!Array.isArray(acc)) {
+        acc = []
+      }
+
+      acc = [...source]
+    } else if (source instanceof Object) {
+      // eslint-disable-next-line
+      for (let [key, value] of Object.entries(source)) {
+        if (value instanceof Object && key in acc) {
+          value = deepMerge(acc[key], value)
+        }
+
+        if (value !== undefined) 
+acc = { ...acc, [key]: value }
+      }
+    }
+  }
+
+  return acc
+}
+
+const buildAgentWarning = (current: TAgent, suggested: TAgent): string => {
+  const message = `# Agent mismatch!\n
+        
+In LearnPack, the agent is in charge of running the LearnPack interface.
+
+You're currently using LearnPack through \`${current}\` but the suggested agent is \`${suggested}\`. 
+
+We recommend strongly recommend changing your agent.
+
+  ${stepsToChangeAgent(suggested)}
+       `
+
+  return message
+}
+
+const stepsToChangeAgent = (agent: TAgent): string => {
+  if (agent === "vscode") {
+    return `
+# Steps to Change Agent to VSCode
+
+1. **Install VSCode**:
+   - Visit the [VSCode website](https://code.visualstudio.com/Download) and download the latest version.
+   - Follow the installation instructions for your operating system.
+
+2. **Install LearnPack VSCode Extension**:
+   - Open VSCode.
+   - Go to the Extensions view by clicking on the Extensions icon in the Activity Bar on the side of the window or by pressing \`Ctrl+Shift+X\`.
+   - Search for "LearnPack" and click "Install".
+   - If the extension is already installed but disabled, enable it.
+
+3. **Run LearnPack in VSCode**:
+   - Open your terminal in VSCode.
+   - Navigate to your LearnPack project directory.
+   - Run the following command:
+     \`\`\`sh
+     learnpack start
+     \`\`\`
+
+We strongly recommend using VSCode for a better learning experience.
+    `
+  }
+
+  if (agent === "os") {
+    return `
+# Steps to Change Agent to OS
+
+This learning package was designed to run outside of VSCode. We strongly recommend closing VSCode and running the package independently.
+
+1. **Close VSCode**:
+   - Save your work and close the VSCode application.
+
+2. **Open a New Terminal**:
+   - Open a terminal or command prompt on your operating system.
+
+3. **Navigate to Your LearnPack Project Directory**:
+   - Use the \`cd\` command to navigate to the directory where your LearnPack project is located.
+
+4. **Run LearnPack**:
+   - Run the following command to start LearnPack:
+     \`\`\`sh
+     learnpack start
+     \`\`\`
+
+We strongly recommend running the package independently for a better learning experience.
+    `
+  }
+
+  return ""
+}
+
+/**
+ * Checks if the 'code' command is available in the terminal.
+ *
+ * @returns {boolean} True if the 'code' command is available, false otherwise.
+ */
+const isCodeCommandAvailable = (): boolean => {
+  return shell.which("code") !== null
+}
+
+/**
+ * Checks if a specific VSCode extension is installed.
+ *
+ * @param {string} extensionName - The name of the extension to check.
+ * @returns {boolean} True if the extension is installed, false otherwise.
+ */
+const isExtensionInstalled = (extensionName: string): boolean => {
+  if (!isCodeCommandAvailable()) {
+    throw new Error(
+      "The 'code' command is not available in the terminal. Please ensure that VSCode is installed and the 'code' command is added to your PATH."
+    )
+  }
+
+  const result = shell.exec("code --list-extensions", { silent: true })
+  return result.stdout.split("\n").includes(extensionName)
+}
+
+const EXTENSION_INSTALLATION_STEPS = `
+# Steps to Install LearnPack VSCode Extension
+
+1. **Open VSCode**:
+   - Launch the Visual Studio Code application on your computer.
+
+2. **Go to Extensions View**:
+   - Click on the Extensions icon in the Activity Bar on the side of the window.
+   - Alternatively, you can open the Extensions view by pressing \`Ctrl+Shift+X\`.
+
+3. **Search for LearnPack**:
+   - In the Extensions view, type "LearnPack" into the search bar.
+
+4. **Install the Extension**:
+   - Find the "LearnPack" extension in the search results and click the "Install" button.
+   - If the extension is already installed but disabled, click the "Enable" button.
+
+5. **Verify Installation**:
+   - Once installed, you can verify the installation by running the following command in the terminal:
+     \`\`\`sh
+     code --list-extensions | grep learn-pack.learnpack-vscode
+     \`\`\`
+   - If the extension is listed, it means the installation was successful.
+
+We strongly recommend using the LearnPack extension in VSCode for a better learning experience.
+`
+
+/**
+ * Installs the LearnPack VSCode extension if the 'code' command is available.
+ *
+ * @param {string} extensionName - The name of the extension to install.
+ * @returns {boolean} True if the installation was successful, false otherwise.
+ */
+const installExtension = (extensionName: string): boolean => {
+  if (!isCodeCommandAvailable()) {
+    throw new Error(
+      "The 'code' command is not available in the terminal. Please ensure that VSCode is installed and the 'code' command is added to your PATH."
+    )
+  }
+
+  const result = shell.exec(`code --install-extension ${extensionName}`, {
+    silent: true,
+  })
+  return result.code === 0
+}