Merge branch 'main' into joan/order-from-config

Author: SamVerschueren

.github/workflows/ci.yaml

@@ -36,3 +36,20 @@ jobs:
         run: pnpm build
       - name: Test
         run: pnpm test
+
+  docs:
+    name: Docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Setup
+        uses: pnpm/action-setup@v4
+        with:
+          version: 8
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install dependencies
+        run: pnpm install
+      - name: Build
+        run: pnpm build
+      - name: Build docs
+        run: pnpm run docs:build

docs/tutorialkit.dev/package.json

@@ -12,16 +12,16 @@
   },
   "dependencies": {
     "@astrojs/check": "^0.7.0",
-    "@astrojs/react": "^3.4.0",
-    "@astrojs/starlight": "^0.23.2",
+    "@astrojs/react": "^3.6.0",
+    "@astrojs/starlight": "^0.23.4",
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",
-    "astro": "^4.8.6",
+    "astro": "^4.10.3",
     "classnames": "^2.5.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "sass": "^1.77.3",
-    "sharp": "^0.32.5",
+    "sass": "^1.77.6",
+    "sharp": "^0.32.6",
     "starlight-links-validator": "^0.9.0",
     "typescript": "^5.4.5"
   },

docs/tutorialkit.dev/src/content/docs/guides/configuration.mdx

@@ -8,9 +8,9 @@ You can configure the appearance and behavior of a TutorialKit lesson by setting
 
 ## Note on inheritance
 
-Some options, like "title," will naturally be unique for each lesson. For others, like "template," the value might be the same across multiple lessons, chapters, or even an entire tutorial. That's why we've made it possible to set some properties on a **chapter**, **part**, or **tutorial** level. We call these values _inherited_. 
+Some options, like "title," will naturally be unique for each lesson. For others, like "template," the value might be the same across multiple lessons, chapters, or even an entire tutorial. That's why we've made it possible to set some properties on a **chapter**, **part**, or **tutorial** level. We call these values _inherited_.
 
-For instance, if you set `template: "simple"` for a given **part**, all chapters and lessons in this **part** will use the "simple" template. 
+For instance, if you set `template: "simple"` for a given **part**, all chapters and lessons in this **part** will use the "simple" template.
 
 It's also possible to override inherited properties on a lower level. For example, if you set `template: "simple"` for a **part**, but `template: "advanced"` for a **lesson**, that specific lesson will use the "advanced" template.
 
@@ -38,16 +38,16 @@ Defines which file should be opened in the [code editor](/guides/ui/#code-editor
 <PropertyTable inherited type="string" />
 
 ##### `previews`
-Configure which ports should be used for the previews allowing you to align the behavior with your demo application's dev server setup. If not specified, the lowest port will be used. 
+Configure which ports should be used for the previews allowing you to align the behavior with your demo application's dev server setup. If not specified, the lowest port will be used.
 
-You can optionally provide these as an array of tuples where the first element is the port number and the second is the name of the preview, or as an object.
+You can optionally provide these as an array of tuples where the first element is the port number and the second is the title of the preview, or as an object.
 <PropertyTable inherited type={'Preview[]'} />
 
 The `Preview` type has the following shape:
 
 ```ts
-type Preview = string 
-    | [port: number, title: string] 
+type Preview = string
+    | [port: number, title: string]
     | { port: number, title: string }
 
 ```
@@ -59,8 +59,8 @@ The main command to be executed. This command will run after the `prepareCommand
 The `Command` type has the following shape:
 
 ```ts
-type Command = string 
-    | [command: string, title: string] 
+type Command = string
+    | [command: string, title: string]
     | { command: string, title: string }
 
 ```
@@ -72,8 +72,8 @@ List of commands to execute sequentially. They are typically used to install dep
 The `Command` type has the following shape:
 
 ```ts
-type Command = string 
-    | [command: string, title: string] 
+type Command = string
+    | [command: string, title: string]
     | { command: string, title: string }
 
 ```
@@ -83,6 +83,10 @@ Configures one or more terminals. TutorialKit provides two types of terminals: r
 
 You can define which terminal panel will be active by default by specifying the `activePanel` value. The value is the given terminal's position in the `panels` array. If you omit the `activePanel` property, the first panel will be the active one.
 
+An interactive terminal will disable the output redirect syntax by default. For instance, you cannot create a file `world.txt` with the contents `hello` using the command `echo hello > world.txt`. The reason is that this could disrupt the lesson if a user overwrites certain files. To allow output redirection, you can change the behavior with the `allowRedirects` setting. You can define this setting either per panel or for all panels at once.
+
+Additionally, you may not want users to run arbitrary commands. For example, if you are creating a lesson about `vitest`, you could specify that the only command the user can run is `vitest` by providing a list of `allowCommands`. Any other command executed by the user will be blocked. You can define the `allowCommands` setting either per panel or for all panels at once.
+
 By default, in every new lesson terminals start a new session. If you want to keep the terminal session between lessons, you can specify the `id` property for a given terminal panel and keep the same `id` across lessons.
 <PropertyTable inherited type="Terminal" />
 
@@ -91,12 +95,14 @@ The `Terminal` type has the following shape:
 ```ts
 type Terminal = {
     panels: TerminalPanel[],
-    activePanel?: number
+    activePanel?: number,
+    allowRedirects?: boolean,
+    allowCommands?: string[]
 }
 
 type TerminalPanel = TerminalType
-    | [type: TerminalType, name: string]
-    | [type: TerminalType, { name: string, id: string }]
+    | [type: TerminalType, title: string]
+    | { type: TerminalType, title?: string, id?: string, allowRedirects?: boolean, allowCommands?: boolean }
 
 type TerminalType = 'terminal' | 'output'
 
@@ -106,10 +112,16 @@ Example value:
 
 ```yaml
 terminal:
+  activePanel: 1
   panels:
     - ['output', 'Dev Server']
-    - ['terminal', { name: 'Command Line', id: 'cmds' }]
-  activePanel: 1
+    - type: terminal
+      id: 'cmds'
+      title: 'Command Line'
+      allowRedirects: true,
+      allowCommands:
+        - ls
+        - echo
 
 ```
 

package.json

@@ -21,7 +21,7 @@
     "conventional-changelog": "^6.0.0",
     "husky": "^9.0.11",
     "is-ci": "^3.0.1",
-    "prettier": "^3.3.1",
+    "prettier": "^3.3.2",
     "prettier-plugin-astro": "^0.13.0",
     "tempfile": "^5.0.0"
   },

packages/astro/package.json

@@ -20,16 +20,17 @@
     "build": "node ./scripts/build.js"
   },
   "dependencies": {
-    "@astrojs/mdx": "^3.0.0",
-    "@astrojs/react": "^3.3.4",
+    "@astrojs/mdx": "^3.1.1",
+    "@astrojs/react": "^3.6.0",
     "@expressive-code/plugin-collapsible-sections": "^0.35.3",
     "@expressive-code/plugin-line-numbers": "^0.35.3",
     "@nanostores/react": "0.7.2",
     "@tutorialkit/components-react": "workspace:*",
     "@tutorialkit/runtime": "workspace:*",
     "@tutorialkit/types": "workspace:*",
-    "@types/react": "^18.2.75",
+    "@types/react": "^18.3.3",
     "@webcontainer/api": "1.2.0",
+    "astro": "^4.10.3",
     "astro-expressive-code": "^0.35.3",
     "chokidar": "3.6.0",
     "fast-glob": "^3.3.2",
@@ -39,19 +40,19 @@
     "mdast-util-directive": "^3.0.0",
     "mdast-util-to-markdown": "^2.1.0",
     "nanostores": "^0.10.3",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "remark-directive": "^3.0.0",
-    "unified": "^11.0.4",
+    "unified": "^11.0.5",
     "unist-util-visit": "^5.0.0",
     "unocss": "^0.59.4",
     "zod": "3.23.8"
   },
   "devDependencies": {
     "@tutorialkit/types": "workspace:*",
-    "@types/mdast": "^4.0.3",
+    "@types/mdast": "^4.0.4",
     "esbuild": "^0.20.2",
-    "esbuild-node-externals": "^1.13.0",
+    "esbuild-node-externals": "^1.13.1",
     "execa": "^9.2.0",
     "typescript": "^5.4.5",
     "vite-plugin-inspect": "0.8.4"

packages/cli/package.json

@@ -31,6 +31,7 @@
     "@babel/types": "7.24.5",
     "@clack/prompts": "^0.7.0",
     "chalk": "^5.3.0",
+    "execa": "^9.2.0",
     "ignore": "^5.3.1",
     "lookpath": "^1.2.2",
     "yargs-parser": "^21.1.1"
@@ -39,11 +40,10 @@
     "@types/babel__generator": "7.6.8",
     "@types/babel__traverse": "7.20.5",
     "@types/fs-extra": "^11.0.4",
-    "@types/node": "^20.12.7",
+    "@types/node": "^20.14.6",
     "@types/yargs-parser": "^21.0.3",
     "esbuild": "^0.20.2",
-    "esbuild-node-externals": "^1.13.0",
-    "execa": "^9.2.0",
+    "esbuild-node-externals": "^1.13.1",
     "fs-extra": "^11.2.0",
     "vitest": "^1.6.0"
   },

packages/cli/src/commands/create/dependencies.ts

@@ -5,11 +5,14 @@ import { parseAstroConfig, replaceArgs } from './astro-config.js';
 import { generate } from './babel.js';
 
 export async function setupEnterpriseConfig(dest: string, flags: CreateOptions) {
-  let editorOrigin = flags.enterprise;
-
   if (!flags.defaults && flags.enterprise === undefined) {
+    // early exit if `--defaults` is provided without `--enterprise`
     return;
-  } else if (editorOrigin) {
+  }
+
+  let editorOrigin = flags.enterprise;
+
+  if (editorOrigin) {
     const error = validateEditorOrigin(editorOrigin);
 
     if (error) {

packages/cli/src/commands/create/enterprise.ts

@@ -6,12 +6,12 @@ import { pkg } from '../../pkg.js';
 import { warnLabel } from '../../utils/messages.js';
 import { runShellCommand } from '../../utils/shell.js';
 import { assertNotCanceled, runTask } from '../../utils/tasks.js';
-import { DEFAULT_VALUES, type CreateOptions } from './options.js';
+import { DEFAULT_VALUES, readFlag, type CreateOptions } from './options.js';
 
 export async function initGitRepo(cwd: string, flags: CreateOptions) {
-  let shouldInitGitRepo = flags.git ?? DEFAULT_VALUES.git;
+  let shouldInitGitRepo = readFlag(flags, 'git');
 
-  if (!flags.defaults && flags.git === undefined) {
+  if (shouldInitGitRepo === undefined) {
     const answer = await prompts.confirm({
       message: 'Initialize a new git repository?',
       initialValue: DEFAULT_VALUES.git,