feat(terminal): add support for redirects and allow specific commands (#76)

Author: SamVerschueren

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
 
 ```
 

packages/components/react/src/Panels/TerminalPanel.tsx

@@ -52,7 +52,7 @@ export function TerminalPanel({ theme, tutorialStore }: TerminalPanelProps) {
             role="tablist"
             aria-orientation="horizontal"
           >
-            {terminalConfig.panels.map(({ type, name }, index) => {
+            {terminalConfig.panels.map(({ type, title }, index) => {
               const selected = tabIndex === index;
 
               return (
@@ -69,7 +69,7 @@ export function TerminalPanel({ theme, tutorialStore }: TerminalPanelProps) {
                         'border-l': index > 0,
                       },
                     )}
-                    title={name}
+                    title={title}
                     aria-selected={selected}
                     onClick={() => setTabIndex(index)}
                   >
@@ -79,7 +79,7 @@ export function TerminalPanel({ theme, tutorialStore }: TerminalPanelProps) {
                         'text-tk-elements-panel-headerTab-iconColorActive': selected,
                       })}
                     ></span>
-                    {name}
+                    {title}
                   </button>
                 </li>
               );

packages/runtime/src/store/terminal.ts

@@ -56,7 +56,7 @@ export class TerminalStore {
         // if the panel is a terminal panel, and this panel didn't exist before, spawn a new JSH process
         this._bootWebContainer(panel)
           .then(async (webcontainerInstance) => {
-            panel.attachProcess(await newJSHProcess(webcontainerInstance, panel));
+            panel.attachProcess(await newJSHProcess(webcontainerInstance, panel, panel.processOptions));
           })
           .catch(() => {
             // do nothing

packages/runtime/src/webcontainer/shell.ts

@@ -2,9 +2,37 @@ import type { WebContainer } from '@webcontainer/api';
 import { withResolvers } from '../utils/promises.js';
 import type { ITerminal } from '../utils/terminal.js';
 
-export async function newJSHProcess(webcontainer: WebContainer, terminal: ITerminal) {
+interface ProcessOptions {
+  /**
+   * Set to `true` if you want to allow redirecting output (e.g. `echo foo > bar`).
+   */
+  allowRedirects: boolean;
+
+  /**
+   * List of commands that are allowed by the JSH process.
+   */
+  allowCommands?: string[];
+}
+
+export async function newJSHProcess(
+  webcontainer: WebContainer,
+  terminal: ITerminal,
+  options: ProcessOptions | undefined,
+) {
+  const args: string[] = [];
+
+  if (!options?.allowRedirects) {
+    // if redirects are turned off, start JSH with `--no-redirects`
+    args.push('--no-redirects');
+  }
+
+  if (Array.isArray(options?.allowCommands)) {
+    // if only a subset of commands is allowed, pass it down to JSH
+    args.push('--allow-commands', options.allowCommands.join(','));
+  }
+
   // we spawn a JSH process with a fallback cols and rows in case the process is not attached yet to a visible terminal
-  const process = await webcontainer.spawn('/bin/jsh', ['--osc'], {
+  const process = await webcontainer.spawn('/bin/jsh', ['--osc', ...args], {
     terminal: {
       cols: terminal.cols ?? 80,
       rows: terminal.rows ?? 15,

packages/runtime/src/webcontainer/terminal-config.spec.ts

@@ -22,14 +22,14 @@ describe('TerminalConfig', () => {
     const config = new TerminalConfig(true);
 
     expect(config.panels.length).toBe(1);
-    expect(config.panels[0].name).toBe('Output');
+    expect(config.panels[0].title).toBe('Output');
   });
 
   it('should have only output panel when config is undefined', () => {
     const config = new TerminalConfig();
 
     expect(config.panels.length).toBe(1);
-    expect(config.panels[0].name).toBe('Output');
+    expect(config.panels[0].title).toBe('Output');
   });
 
   it('should have panels with custom names', () => {
@@ -40,31 +40,157 @@ describe('TerminalConfig', () => {
       ],
     });
 
-    expect(config.panels[0].name).toBe('Foo');
-    expect(config.panels[1].name).toBe('Bar');
+    expect(config.panels[0].title).toBe('Foo');
+    expect(config.panels[1].title).toBe('Bar');
   });
 
   it('should have panels with custom names and ids', () => {
     const config = new TerminalConfig({
       panels: [
-        ['terminal', { name: 'Foo', id: 'foo' }],
-        ['terminal', { name: 'Bar', id: 'bar' }],
+        { type: 'terminal', title: 'Foo', id: 'foo' },
+        { type: 'terminal', title: 'Bar', id: 'bar' },
       ],
     });
 
-    expect(config.panels[0].name).toBe('Foo');
+    expect(config.panels[0].title).toBe('Foo');
     expect(config.panels[0].id).toBe('foo');
-    expect(config.panels[1].name).toBe('Bar');
+    expect(config.panels[0].processOptions).toEqual({
+      allowRedirects: false,
+      allowCommands: undefined,
+    });
+    expect(config.panels[1].title).toBe('Bar');
     expect(config.panels[1].id).toBe('bar');
+    expect(config.panels[1].processOptions).toEqual({
+      allowRedirects: false,
+      allowCommands: undefined,
+    });
+  });
+
+  it('should allow redirects and only allow certain commands when providing a panel type', () => {
+    const config = new TerminalConfig({
+      allowRedirects: true,
+      allowCommands: ['echo'],
+      panels: 'terminal',
+    });
+
+    expect(config.panels[0].title).toBe('Terminal');
+    expect(config.panels[0].processOptions).toEqual({
+      allowRedirects: true,
+      allowCommands: ['echo'],
+    });
+  });
+
+  it('should allow redirects and only allow certain commands when providing a list of panel types', () => {
+    const config = new TerminalConfig({
+      allowRedirects: true,
+      allowCommands: ['echo'],
+      panels: ['terminal', 'terminal', 'output'],
+    });
+
+    expect(config.panels[0].title).toBe('Terminal');
+    expect(config.panels[0].processOptions).toEqual({
+      allowRedirects: true,
+      allowCommands: ['echo'],
+    });
+
+    expect(config.panels[1].title).toBe('Terminal 1');
+    expect(config.panels[1].processOptions).toEqual({
+      allowRedirects: true,
+      allowCommands: ['echo'],
+    });
+
+    expect(config.panels[2].title).toBe('Output');
+    expect(config.panels[2].processOptions).toBeUndefined();
+  });
+
+  it('should allow redirects and only allow certain commands when providing a list of panel tuples', () => {
+    const config = new TerminalConfig({
+      allowRedirects: true,
+      allowCommands: ['echo'],
+      panels: [
+        ['terminal', 'TERM 1'],
+        ['terminal', 'TERM 2'],
+        ['output', 'OUT'],
+      ],
+    });
+
+    expect(config.panels[0].title).toBe('TERM 1');
+    expect(config.panels[0].processOptions).toEqual({
+      allowRedirects: true,
+      allowCommands: ['echo'],
+    });
+
+    expect(config.panels[1].title).toBe('TERM 2');
+    expect(config.panels[1].processOptions).toEqual({
+      allowRedirects: true,
+      allowCommands: ['echo'],
+    });
+
+    expect(config.panels[2].title).toBe('OUT');
+    expect(config.panels[2].processOptions).toBeUndefined();
+  });
+
+  it('should allow redirects and only allow certain commands when providing a list of panel objects', () => {
+    const config = new TerminalConfig({
+      allowRedirects: true,
+      allowCommands: ['echo'],
+      panels: [
+        { type: 'terminal', title: 'TERM 1' },
+        { type: 'terminal', title: 'TERM 2' },
+        { type: 'output', title: 'OUT' },
+      ],
+    });
+
+    expect(config.panels[0].title).toBe('TERM 1');
+    expect(config.panels[0].processOptions).toEqual({
+      allowRedirects: true,
+      allowCommands: ['echo'],
+    });
+
+    expect(config.panels[1].title).toBe('TERM 2');
+    expect(config.panels[1].processOptions).toEqual({
+      allowRedirects: true,
+      allowCommands: ['echo'],
+    });
+
+    expect(config.panels[2].title).toBe('OUT');
+    expect(config.panels[2].processOptions).toBeUndefined();
+  });
+
+  it('should allow overwriting `allowRedirects` and `allowCommands` per panel', () => {
+    const config = new TerminalConfig({
+      allowRedirects: true,
+      allowCommands: ['echo'],
+      panels: [
+        { type: 'terminal', title: 'TERM 1', allowRedirects: false },
+        { type: 'terminal', title: 'TERM 2', allowCommands: ['ls'] },
+        { type: 'output', title: 'OUT', allowRedirects: false },
+      ],
+    });
+
+    expect(config.panels[0].title).toBe('TERM 1');
+    expect(config.panels[0].processOptions).toEqual({
+      allowRedirects: false,
+      allowCommands: ['echo'],
+    });
+
+    expect(config.panels[1].title).toBe('TERM 2');
+    expect(config.panels[1].processOptions).toEqual({
+      allowRedirects: true,
+      allowCommands: ['ls'],
+    });
+
+    expect(config.panels[2].title).toBe('OUT');
+    expect(config.panels[2].processOptions).toBeUndefined();
   });
 
   it('should have panels and activePanel with inferred names', () => {
     const config = new TerminalConfig({
       panels: ['output', 'terminal', 'terminal'],
     });
 
-    expect(config.panels[0].name).toBe('Output');
-    expect(config.panels[1].name).toBe('Terminal');
-    expect(config.panels[2].name).toBe('Terminal 1');
+    expect(config.panels[0].title).toBe('Output');
+    expect(config.panels[1].title).toBe('Terminal');
+    expect(config.panels[2].title).toBe('Terminal 1');
   });
 });