@tutorialkit-rb/runtime 1.5.2-rb.0.1.0

package/dist/store/index.js

@@ -0,0 +1,316 @@
+import { atom } from 'nanostores';
+import { LessonFilesFetcher } from '../lesson-files.js';
+import { newTask } from '../tasks.js';
+import { bootStatus, unblockBoot } from '../webcontainer/on-demand-boot.js';
+import { StepsController } from '../webcontainer/steps.js';
+import { EditorStore } from './editor.js';
+import { PreviewsStore } from './previews.js';
+import { TerminalStore } from './terminal.js';
+import { TutorialRunner } from './tutorial-runner.js';
+export class TutorialStore {
+    _webcontainer;
+    _runner;
+    _previewsStore;
+    _editorStore;
+    _terminalStore;
+    _stepController = new StepsController();
+    _lessonFilesFetcher;
+    _lessonTask;
+    _lesson;
+    _ref = atom(1);
+    _themeRef = atom(1);
+    _lessonFiles;
+    _lessonSolution;
+    _lessonTemplate;
+    /**
+     * Whether or not the current lesson is fully loaded in WebContainer
+     * and in every stores.
+     */
+    lessonFullyLoaded = atom(false);
+    constructor({ useAuth, webcontainer, basePathname }) {
+        this._webcontainer = webcontainer;
+        this._editorStore = new EditorStore();
+        this._lessonFilesFetcher = new LessonFilesFetcher(basePathname);
+        this._previewsStore = new PreviewsStore(this._webcontainer);
+        this._terminalStore = new TerminalStore(this._webcontainer, useAuth);
+        this._runner = new TutorialRunner(this._webcontainer, this._terminalStore, this._editorStore, this._stepController);
+        /**
+         * By having this code under `import.meta.hot`, it gets:
+         *  - ignored on server side where it shouldn't run
+         *  - discarded when doing a production build
+         */
+        if (import.meta.hot) {
+            import.meta.hot.on('tk:refresh-wc-files', async (hotFilesRefs) => {
+                let shouldUpdate = false;
+                for (const filesRef of hotFilesRefs) {
+                    const result = await this._lessonFilesFetcher.invalidate(filesRef);
+                    switch (result.type) {
+                        case 'none': {
+                            break;
+                        }
+                        case 'files': {
+                            if (this._lesson?.files[0] === filesRef) {
+                                shouldUpdate = true;
+                                this._lesson.files[1] = Object.keys(result.files).sort();
+                                this._lessonFiles = result.files;
+                            }
+                            break;
+                        }
+                        case 'solution': {
+                            if (this._lesson?.solution[0] === filesRef) {
+                                shouldUpdate = true;
+                                this._lesson.solution[1] = Object.keys(result.files).sort();
+                                this._lessonSolution = result.files;
+                            }
+                            break;
+                        }
+                        case 'template': {
+                            shouldUpdate = true;
+                            this._lessonTemplate = result.files;
+                            break;
+                        }
+                    }
+                }
+                if (shouldUpdate && this._lesson) {
+                    this._lessonTask?.cancel();
+                    const files = this._lessonFiles ?? {};
+                    const template = this._lessonTemplate;
+                    this._lessonTask = newTask(async (signal) => {
+                        const preparePromise = this._runner.prepareFiles({ template, files, signal });
+                        this._runner.runCommands();
+                        this._editorStore.setDocuments(files);
+                        await preparePromise;
+                    }, { ignoreCancel: true });
+                }
+            });
+        }
+    }
+    /** @internal */
+    setLesson(lesson, options = {}) {
+        if (lesson === this._lesson) {
+            return;
+        }
+        this._lessonTask?.cancel();
+        this._ref.set(1 + (this._ref.value || 0));
+        this._lesson = lesson;
+        this.lessonFullyLoaded.set(false);
+        this._previewsStore.setPreviews(lesson.data.previews ?? true);
+        this._terminalStore.setTerminalConfiguration(lesson.data.terminal);
+        this._editorStore.setEditorConfig(lesson.data.editor);
+        this._runner.setCommands(lesson.data);
+        this._editorStore.setDocuments(lesson.files);
+        if (options.ssr) {
+            return;
+        }
+        this._runner.setWatchFromWebContainer(lesson.data.filesystem?.watch ?? false);
+        this._lessonTask = newTask(async (signal) => {
+            const templatePromise = this._lessonFilesFetcher.getLessonTemplate(lesson);
+            const filesPromise = this._lessonFilesFetcher.getLessonFiles(lesson);
+            const removePaths = lesson?.data?.custom?.fs?.remove;
+            const preparePromise = this._runner.prepareFiles({
+                template: templatePromise,
+                files: filesPromise,
+                signal,
+                removePaths,
+            });
+            this._runner.runCommands();
+            const [template, solution, files] = await Promise.all([
+                templatePromise,
+                this._lessonFilesFetcher.getLessonSolution(lesson),
+                filesPromise,
+            ]);
+            signal.throwIfAborted();
+            this._lessonTemplate = template;
+            this._lessonFiles = files;
+            this._lessonSolution = solution;
+            this._editorStore.setDocuments(files);
+            if (lesson.data.focus === undefined) {
+                this._editorStore.setSelectedFile(undefined);
+            }
+            else if (files[lesson.data.focus] !== undefined) {
+                this._editorStore.setSelectedFile(lesson.data.focus);
+            }
+            await preparePromise;
+            signal.throwIfAborted();
+            this.lessonFullyLoaded.set(true);
+        }, { ignoreCancel: true });
+    }
+    /** Instances of the preview tabs. */
+    get previews() {
+        return this._previewsStore.previews;
+    }
+    /** Configuration and instances of the terminal */
+    get terminalConfig() {
+        return this._terminalStore.terminalConfig;
+    }
+    /** Configuration of the editor and file tree */
+    get editorConfig() {
+        return this._editorStore.editorConfig;
+    }
+    /** File that's currently open in the editor */
+    get currentDocument() {
+        return this._editorStore.currentDocument;
+    }
+    /** Status of the webcontainer's booting */
+    get bootStatus() {
+        return bootStatus;
+    }
+    /** Files that are available in the editor. */
+    get documents() {
+        return this._editorStore.documents;
+    }
+    /** Paths of the files that are available in the lesson */
+    get files() {
+        return this._editorStore.files;
+    }
+    /** File that's currently selected in the file tree */
+    get selectedFile() {
+        return this._editorStore.selectedFile;
+    }
+    /** Currently active lesson */
+    get lesson() {
+        return this._lesson;
+    }
+    /** @internal */
+    get ref() {
+        return this._ref;
+    }
+    /** @internal */
+    get themeRef() {
+        return this._themeRef;
+    }
+    /**
+     * Steps that the runner is or will be executing.
+     *
+     * @internal
+     */
+    get steps() {
+        return this._stepController.steps;
+    }
+    /** Check if file tree is visible */
+    hasFileTree() {
+        if (!this._lesson) {
+            return false;
+        }
+        return this.editorConfig.get().fileTree.visible;
+    }
+    /** Check if editor is visible */
+    hasEditor() {
+        if (!this._lesson) {
+            return false;
+        }
+        return this.editorConfig.get().visible;
+    }
+    /** Check if lesson has any previews set */
+    hasPreviews() {
+        if (!this._lesson) {
+            return false;
+        }
+        const { previews } = this._lesson.data;
+        return previews !== false;
+    }
+    /** Check if lesson has any terminals set */
+    hasTerminalPanel() {
+        return this._terminalStore.hasTerminalPanel();
+    }
+    /** Check if lesson has solution files set */
+    hasSolution() {
+        return !!this._lesson && Object.keys(this._lesson.solution[1]).length >= 1;
+    }
+    /** Unlock webcontainer's boot process if it was in `'blocked'` state */
+    unblockBoot() {
+        unblockBoot();
+    }
+    /** Reset changed files back to lesson's initial state */
+    reset() {
+        const isReady = this.lessonFullyLoaded.value;
+        if (!isReady || !this._lessonFiles) {
+            return;
+        }
+        this._editorStore.setDocuments(this._lessonFiles);
+        this._runner.updateFiles(this._lessonFiles);
+    }
+    /** Apply lesson solution into the lesson files */
+    solve() {
+        const isReady = this.lessonFullyLoaded.value;
+        if (!isReady || !this._lessonSolution) {
+            return;
+        }
+        const files = { ...this._lessonFiles, ...this._lessonSolution };
+        this._editorStore.setDocuments(files);
+        this._runner.updateFiles(files);
+    }
+    /** Set file from file tree as selected */
+    setSelectedFile(filePath) {
+        this._editorStore.setSelectedFile(filePath);
+    }
+    /** Add new file to file tree */
+    async addFile(filePath) {
+        // always select the existing or newly created file
+        this.setSelectedFile(filePath);
+        // prevent creating duplicates
+        if (this._editorStore.files.get().find((file) => file.path === filePath)) {
+            return;
+        }
+        if (await this._runner.fileExists(filePath)) {
+            throw new Error('FILE_EXISTS');
+        }
+        this._editorStore.addFileOrFolder({ path: filePath, type: 'file' });
+        this._runner.updateFile(filePath, '');
+    }
+    /** Add new folder to file tree */
+    async addFolder(folderPath) {
+        // prevent creating duplicates
+        if (this._editorStore.files.get().some((file) => file.path.startsWith(folderPath))) {
+            return;
+        }
+        if (await this._runner.folderExists(folderPath)) {
+            throw new Error('FOLDER_EXISTS');
+        }
+        this._editorStore.addFileOrFolder({ path: folderPath, type: 'folder' });
+        this._runner.createFolder(folderPath);
+    }
+    /** Update contents of file */
+    updateFile(filePath, content) {
+        const hasChanged = this._editorStore.updateFile(filePath, content);
+        if (hasChanged) {
+            this._runner.updateFile(filePath, content);
+        }
+    }
+    /** Update content of the active file */
+    setCurrentDocumentContent(newContent) {
+        const filePath = this.currentDocument.get()?.filePath;
+        if (!filePath) {
+            return;
+        }
+        this.updateFile(filePath, newContent);
+    }
+    /** Update scroll position of the file in editor */
+    setCurrentDocumentScrollPosition(position) {
+        const editorDocument = this.currentDocument.get();
+        if (!editorDocument) {
+            return;
+        }
+        const { filePath } = editorDocument;
+        this._editorStore.updateScrollPosition(filePath, position);
+    }
+    /** @internal */
+    attachTerminal(id, terminal) {
+        this._terminalStore.attachTerminal(id, terminal);
+    }
+    /** Callback that should be called when terminal resizes */
+    onTerminalResize(cols, rows) {
+        if (cols && rows) {
+            this._terminalStore.onTerminalResize(cols, rows);
+            this._runner.onTerminalResize(cols, rows);
+        }
+    }
+    /** Listen for file changes made in the editor */
+    onDocumentChanged(filePath, callback) {
+        return this._editorStore.onDocumentChanged(filePath, callback);
+    }
+    /** Take snapshot of the current state of the lesson */
+    takeSnapshot() {
+        return this._runner.takeSnapshot();
+    }
+}

package/dist/store/previews.d.ts

@@ -0,0 +1,19 @@
+import type { PreviewSchema } from '@tutorialkit-rb/types';
+import type { WebContainer } from '@webcontainer/api';
+import { PreviewInfo } from '../webcontainer/preview-info.js';
+export declare class PreviewsStore {
+    private _availablePreviews;
+    private _previewsLayout;
+    /**
+     * Atom representing the current previews. If it's an empty array or none of
+     * the previews are ready, then no preview can be shown.
+     */
+    previews: import("nanostores").WritableAtom<PreviewInfo[]>;
+    constructor(webcontainerPromise: Promise<WebContainer>);
+    private _init;
+    /**
+     * Set the expected port for the preview to show. If this is not set,
+     * the port of the first server that is ready will be used.
+     */
+    setPreviews(config: PreviewSchema): void;
+}

package/dist/store/previews.js

@@ -0,0 +1,80 @@
+import { atom } from 'nanostores';
+import { PortInfo } from '../webcontainer/port-info.js';
+import { PreviewInfo } from '../webcontainer/preview-info.js';
+export class PreviewsStore {
+    _availablePreviews = new Map();
+    _previewsLayout = [];
+    /**
+     * Atom representing the current previews. If it's an empty array or none of
+     * the previews are ready, then no preview can be shown.
+     */
+    previews = atom([]);
+    constructor(webcontainerPromise) {
+        this._init(webcontainerPromise);
+    }
+    async _init(webcontainerPromise) {
+        const webcontainer = await webcontainerPromise;
+        webcontainer.on('port', (port, type, url) => {
+            let portInfo = this._availablePreviews.get(port);
+            if (!portInfo) {
+                portInfo = new PortInfo(port, url, type === 'open');
+                this._availablePreviews.set(port, portInfo);
+            }
+            portInfo.ready = type === 'open';
+            portInfo.origin = url;
+            if (this._previewsLayout.length === 0) {
+                this.previews.set([new PreviewInfo({}, portInfo)]);
+            }
+            else {
+                this._previewsLayout = [...this._previewsLayout];
+                this.previews.set(this._previewsLayout);
+            }
+        });
+    }
+    /**
+     * Set the expected port for the preview to show. If this is not set,
+     * the port of the first server that is ready will be used.
+     */
+    setPreviews(config) {
+        if (config === false) {
+            // clear the previews if they are turned off
+            this.previews.set([]);
+            return;
+        }
+        // if the schema is `true`, we just use the default empty array
+        const previews = config === true ? [] : (config ?? []);
+        const previewInfos = previews.map((previewConfig) => {
+            const preview = PreviewInfo.parse(previewConfig);
+            let portInfo = this._availablePreviews.get(preview.port);
+            if (!portInfo) {
+                portInfo = new PortInfo(preview.port);
+                this._availablePreviews.set(preview.port, portInfo);
+            }
+            return new PreviewInfo(preview, portInfo);
+        });
+        let areDifferent = previewInfos.length != this._previewsLayout.length;
+        if (!areDifferent) {
+            for (let i = 0; i < previewInfos.length; i++) {
+                areDifferent = !PreviewInfo.equals(previewInfos[i], this._previewsLayout[i]);
+                if (areDifferent) {
+                    break;
+                }
+            }
+        }
+        if (!areDifferent) {
+            return;
+        }
+        this._previewsLayout = previewInfos;
+        /**
+         * If a port is provided and the preview is already ready we update the previewUrl.
+         * If no port is provided we default to the first preview ever to ready if there are any.
+         */
+        if (previews.length === 0) {
+            const firstPreview = this._availablePreviews.values().next().value;
+            this.previews.set(firstPreview ? [firstPreview] : []);
+        }
+        else {
+            this.previews.set(this._previewsLayout);
+        }
+    }
+}

package/dist/store/terminal.d.ts

@@ -0,0 +1,24 @@
+import type { TerminalSchema } from '@tutorialkit-rb/types';
+import { WebContainer } from '@webcontainer/api';
+import { type ITerminal } from '../utils/terminal.js';
+import { TerminalConfig } from '../webcontainer/terminal-config.js';
+export declare class TerminalStore {
+    private _webcontainer;
+    private _useAuth;
+    terminalConfig: import("nanostores").WritableAtom<TerminalConfig>;
+    private _output;
+    private _webcontainerLoaded;
+    constructor(_webcontainer: Promise<WebContainer>, _useAuth: boolean);
+    getOutputPanel(): ITerminal | undefined;
+    hasTerminalPanel(): boolean;
+    setTerminalConfiguration(config?: TerminalSchema): void;
+    /**
+     * Attaches the provided terminal with the panel matching the provided ID.
+     *
+     * @param id The ID of the panel to attach the terminal with.
+     * @param terminal The terminal to hook up to the JSH process.
+     */
+    attachTerminal(id: string, terminal: ITerminal): Promise<void>;
+    onTerminalResize(cols: number, rows: number): void;
+    private _bootWebContainer;
+}

package/dist/store/terminal.js

@@ -0,0 +1,128 @@
+import { WebContainer, auth } from '@webcontainer/api';
+import { atom } from 'nanostores';
+import { tick } from '../utils/promises.js';
+import { isWebContainerSupported } from '../utils/support.js';
+import { clearTerminal, escapeCodes } from '../utils/terminal.js';
+import { newJSHProcess } from '../webcontainer/shell.js';
+import { TerminalConfig, TerminalPanel } from '../webcontainer/terminal-config.js';
+export class TerminalStore {
+    _webcontainer;
+    _useAuth;
+    terminalConfig = atom(new TerminalConfig());
+    _output = undefined;
+    _webcontainerLoaded = false;
+    constructor(_webcontainer, _useAuth) {
+        this._webcontainer = _webcontainer;
+        this._useAuth = _useAuth;
+        this._webcontainer.then(() => {
+            this._webcontainerLoaded = true;
+        });
+    }
+    getOutputPanel() {
+        return this._output;
+    }
+    hasTerminalPanel() {
+        return this.terminalConfig.get().panels.length > 0;
+    }
+    setTerminalConfiguration(config) {
+        const oldTerminalConfig = this.terminalConfig.get();
+        const newTerminalConfig = new TerminalConfig(config);
+        // iterate over the old terminal config and make a list of all terminal panels
+        const panelMap = new Map(oldTerminalConfig.panels.map((panel) => [panel.id, panel]));
+        // iterate over the new terminal panels and try to re-use the old terminal with the new panel
+        for (const panel of newTerminalConfig.panels) {
+            const oldPanel = panelMap.get(panel.id);
+            panelMap.delete(panel.id);
+            if (oldPanel?.terminal) {
+                // if we found a previous panel with the same id, attach that terminal to the new panel
+                panel.attachTerminal(oldPanel.terminal);
+            }
+            if (panel.type === 'output') {
+                this._output = panel;
+            }
+            if (panel.type === 'terminal' && !oldPanel) {
+                // 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.processOptions));
+                    // this.terminalConfig.notify(this.terminalConfig.get());
+                })
+                    .catch(() => {
+                    // do nothing
+                });
+            }
+        }
+        // kill all old processes which we couldn't re-use
+        for (const panel of panelMap.values()) {
+            panel.process?.kill();
+        }
+        this.terminalConfig.set(newTerminalConfig);
+    }
+    /**
+     * Attaches the provided terminal with the panel matching the provided ID.
+     *
+     * @param id The ID of the panel to attach the terminal with.
+     * @param terminal The terminal to hook up to the JSH process.
+     */
+    async attachTerminal(id, terminal) {
+        const panel = this.terminalConfig.get().panels.find((panel) => panel.id === id);
+        if (!panel) {
+            // if we don't have a panel with the provided id, just exit
+            return;
+        }
+        panel.attachTerminal(terminal);
+    }
+    onTerminalResize(cols, rows) {
+        // iterate over all terminal panels and resize all processes
+        for (const panel of this.terminalConfig.get().panels) {
+            panel.process?.resize({ cols, rows });
+        }
+    }
+    async _bootWebContainer(terminal) {
+        validateWebContainerSupported(terminal);
+        const isLoaded = this._webcontainerLoaded;
+        if (this._useAuth && !isLoaded) {
+            terminal.write('Waiting for authentication to complete...');
+            await auth.loggedIn();
+            clearTerminal(terminal);
+        }
+        if (!isLoaded) {
+            terminal.write('Booting WebContainer...');
+        }
+        try {
+            const webcontainerInstance = await this._webcontainer;
+            if (!isLoaded) {
+                clearTerminal(terminal);
+            }
+            return webcontainerInstance;
+        }
+        catch (error) {
+            clearTerminal(terminal);
+            await tick();
+            terminal.write([
+                escapeCodes.red(`Looks like your browser's configuration is blocking WebContainers.`),
+                '',
+                `Let's troubleshoot this!`,
+                '',
+                'Read more at:',
+                'https://webcontainers.io/guides/browser-config',
+                '',
+            ].join('\n'));
+            throw error;
+        }
+    }
+}
+function validateWebContainerSupported(terminal) {
+    if (!isWebContainerSupported()) {
+        terminal.write([
+            escapeCodes.red('Incompatible Web Browser'),
+            '',
+            `WebContainers currently work in Chromium-based browsers, Firefox, and Safari 16.4. We're hoping to add support for more browsers as they implement the necessary Web Platform features.`,
+            '',
+            'Read more about browser support:',
+            'https://webcontainers.io/guides/browser-support',
+            '',
+        ].join('\n'));
+        throw new Error('Incompatible Web Browser');
+    }
+}