epicshop 6.74.3 → 6.75.1

package/README.md

@@ -41,8 +41,8 @@ epicshop start <workshop>
 
 ### Helpful commands
 
-- `epicshop add <repo-name> [destination]`: clone a workshop from the
-  `epicweb-dev` GitHub org
+- `epicshop add <repo-name[#ref]> [destination]`: clone a workshop from the
+  `epicweb-dev` GitHub org (use `#` to pin a tag, branch, or commit)
 - `epicshop list`: list your workshops
 - `epicshop open`: open a workshop in your editor
 - `epicshop update`: pull the latest workshop changes

package/dist/cli.js

@@ -158,7 +158,7 @@ const cli = yargs(args)
     .command('add [repo-name] [destination]', 'Add a workshop by cloning from epicweb-dev GitHub org', (yargs) => {
     return yargs
         .positional('repo-name', {
-        describe: 'Repository name from epicweb-dev org (optional, shows list if omitted)',
+        describe: 'Repository name from epicweb-dev org (optional, shows list if omitted). Use <repo>#<tag|branch|commit> to pin a ref.',
         type: 'string',
     })
         .positional('destination', {
@@ -179,7 +179,8 @@ const cli = yargs(args)
         .example('$0 add', 'Show available workshops to add')
         .example('$0 add full-stack-foundations', 'Clone and set up the full-stack-foundations workshop')
         .example('$0 add web-forms --directory ~/my-workshops', 'Clone workshop to a custom directory')
-        .example('$0 add react-fundamentals ~/Desktop/react-fundamentals', 'Clone workshop to a specific destination directory');
+        .example('$0 add react-fundamentals ~/Desktop/react-fundamentals', 'Clone workshop to a specific destination directory')
+        .example('$0 add react-fundamentals#v1.2.0', 'Clone a workshop at a specific tag, branch, or commit');
 }, async (argv) => {
     const { add } = await import("./commands/workshops.js");
     const result = await add({
@@ -758,7 +759,7 @@ const cli = yargs(args)
     })
         .example('$0 playground', 'Show current playground status')
         .example('$0 playground show', 'Show current playground status')
-        .example('$0 playground set', 'Set playground (auto-detect next)')
+        .example('$0 playground set', 'Select a playground app to set (defaults to next step)')
         .example('$0 playground set 1.2.problem', 'Set to specific step')
         .example('$0 playground set --exercise 1 --step 2', 'Set with options')
         .example('$0 playground saved', 'Interactively select a saved playground')
@@ -797,18 +798,11 @@ const cli = yargs(args)
                 stepNumber = parsed.stepNumber ?? stepNumber;
                 type = parsed.type ?? type;
             }
-            // If no specific target, check if we should show interactive or auto
+            // If no specific target, prompt for selection
             if (!exerciseNumber && !stepNumber && !type) {
-                // Auto-detect next step or show interactive
-                const result = await set({ silent: argv.silent });
-                if (!result.success) {
-                    // If auto-detect fails, try interactive
-                    const interactiveResult = await selectAndSet({
-                        silent: argv.silent,
-                    });
-                    if (!interactiveResult.success)
-                        process.exit(1);
-                }
+                const result = await selectAndSet({ silent: argv.silent });
+                if (!result.success)
+                    process.exit(1);
             }
             else {
                 const result = await set({
@@ -947,7 +941,7 @@ const cli = yargs(args)
     .command('diff [app1] [app2]', 'Show differences between apps or playground vs solution (context-aware)', (yargs) => {
     return yargs
         .positional('app1', {
-        describe: 'First app identifier (e.g., 01.02.problem). If omitted, shows playground vs solution.',
+        describe: 'First app identifier (e.g., 01.02.problem). If omitted, prompts with playground vs solution as the default.',
         type: 'string',
     })
         .positional('app2', {
@@ -960,7 +954,7 @@ const cli = yargs(args)
         description: 'Run without output logs',
         default: false,
     })
-        .example('$0 diff', 'Show diff between playground and solution')
+        .example('$0 diff', 'Select apps to diff (defaults to playground vs solution)')
         .example('$0 diff 01.02.problem 01.02.solution', 'Show diff between two apps');
 }, async (argv) => {
     const { findWorkshopRoot } = await import("./commands/workshops.js");
@@ -972,7 +966,7 @@ const cli = yargs(args)
     const originalCwd = process.cwd();
     process.chdir(workshopRoot);
     try {
-        const { showProgressDiff, showDiffBetweenApps } = await import("./commands/diff.js");
+        const { showDiffBetweenApps, selectAndShowDiff } = await import("./commands/diff.js");
         if (argv.app1 && argv.app2) {
             const result = await showDiffBetweenApps({
                 app1: argv.app1,
@@ -987,7 +981,7 @@ const cli = yargs(args)
             process.exit(1);
         }
         else {
-            const result = await showProgressDiff({ silent: argv.silent });
+            const result = await selectAndShowDiff({ silent: argv.silent });
             if (!result.success)
                 process.exit(1);
         }
@@ -1552,8 +1546,8 @@ try {
                 const originalCwd = process.cwd();
                 process.chdir(wsRoot);
                 try {
-                    const { showProgressDiff } = await import("./commands/diff.js");
-                    const result = await showProgressDiff({});
+                    const { selectAndShowDiff } = await import("./commands/diff.js");
+                    const result = await selectAndShowDiff({});
                     if (!result.success)
                         process.exit(1);
                 }

package/dist/commands/diff.d.ts

@@ -15,6 +15,12 @@ export type DiffOptions = {
 export declare function showProgressDiff(options?: {
     silent?: boolean;
 }): Promise<DiffResult>;
+/**
+ * Interactive diff selection between two apps
+ */
+export declare function selectAndShowDiff(options?: {
+    silent?: boolean;
+}): Promise<DiffResult>;
 /**
  * Show diff between two specific apps
  */

package/dist/commands/diff.js

@@ -1,4 +1,6 @@
 import chalk from 'chalk';
+import { matchSorter } from 'match-sorter';
+import { assertCanPrompt } from "../utils/cli-runtime.js";
 /**
  * Show diff between the current playground and its solution
  */
@@ -47,6 +49,119 @@ export async function showProgressDiff(options = {}) {
         };
     }
 }
+/**
+ * Interactive diff selection between two apps
+ */
+export async function selectAndShowDiff(options = {}) {
+    const { silent = false } = options;
+    try {
+        const { findSolutionDir, getAppDisplayName, getApps, getFullPathFromAppName, init, isPlaygroundApp, } = await import('@epic-web/workshop-utils/apps.server');
+        const { getDiffOutputWithRelativePaths } = await import('@epic-web/workshop-utils/diff.server');
+        await init();
+        assertCanPrompt({
+            reason: 'select apps to diff',
+            hints: [
+                'Provide the apps directly: npx epicshop diff 01.02.problem 01.02.solution',
+            ],
+        });
+        const { search } = await import('@inquirer/prompts');
+        const apps = await getApps();
+        if (apps.length < 2) {
+            throw new Error('Need at least two apps to diff');
+        }
+        const playgroundApp = apps.find(isPlaygroundApp);
+        let defaultFirstApp = playgroundApp;
+        let defaultSecondApp = undefined;
+        if (playgroundApp) {
+            try {
+                const solutionDir = await findSolutionDir({
+                    fullPath: await getFullPathFromAppName(playgroundApp.appName),
+                });
+                defaultSecondApp = apps.find((app) => app.fullPath === solutionDir);
+            }
+            catch {
+                // Ignore default selection errors; still allow interactive selection.
+            }
+        }
+        const choices = apps.map((app) => ({
+            name: getAppDisplayName(app, apps),
+            value: app,
+            description: app.fullPath,
+        }));
+        const orderChoices = (allChoices, preferredName) => {
+            if (!preferredName)
+                return allChoices;
+            const preferred = allChoices.find((choice) => choice.value.name === preferredName);
+            if (!preferred)
+                return allChoices;
+            return [
+                preferred,
+                ...allChoices.filter((choice) => choice.value.name !== preferredName),
+            ];
+        };
+        const selectApp = async (message, options = {}) => {
+            const { excludeName, preferredName } = options;
+            const availableChoices = excludeName
+                ? choices.filter((choice) => choice.value.name !== excludeName)
+                : choices;
+            const orderedChoices = orderChoices(availableChoices, preferredName);
+            return search({
+                message,
+                source: async (input) => {
+                    if (!input)
+                        return orderedChoices;
+                    return matchSorter(availableChoices, input, {
+                        keys: ['name', 'value.name', 'description'],
+                    });
+                },
+            });
+        };
+        try {
+            const app1 = await selectApp('Select the first app to diff:', {
+                preferredName: defaultFirstApp?.name,
+            });
+            const app2 = await selectApp('Select the second app to diff:', {
+                excludeName: app1.name,
+                preferredName: defaultSecondApp?.name === app1.name
+                    ? undefined
+                    : defaultSecondApp?.name,
+            });
+            const diffCode = await getDiffOutputWithRelativePaths(app1, app2);
+            const app1Label = getAppDisplayName(app1, apps);
+            const app2Label = getAppDisplayName(app2, apps);
+            if (!diffCode) {
+                if (!silent) {
+                    console.log(chalk.green('✓ No differences between the apps!'));
+                }
+                return { success: true, message: 'No changes', diff: '' };
+            }
+            if (!silent) {
+                console.log(chalk.bold.cyan(`\n📋 Diff: ${app1Label} vs ${app2Label}\n`));
+                console.log(chalk.gray(`Lines starting with - are in ${app1Label} but not ${app2Label}`));
+                console.log(chalk.gray(`Lines starting with + are in ${app2Label} but not ${app1Label}\n`));
+                console.log(formatDiff(diffCode));
+            }
+            return { success: true, diff: diffCode };
+        }
+        catch (error) {
+            if (error.message === 'USER_QUIT') {
+                return { success: false, message: 'Cancelled' };
+            }
+            throw error;
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!silent) {
+            console.error(chalk.red(`❌ Failed to generate diff: ${message}`));
+        }
+        return {
+            success: false,
+            message,
+            error: error instanceof Error ? error : new Error(message),
+        };
+    }
+}
 /**
  * Show diff between two specific apps
  */

package/dist/commands/playground.js

@@ -1,6 +1,48 @@
 import chalk from 'chalk';
 import { matchSorter } from 'match-sorter';
 import { assertCanPrompt } from "../utils/cli-runtime.js";
+/**
+ * Score progress items for sorting to find the next incomplete step
+ */
+function scoreProgress(a) {
+    if (a.type === 'workshop-instructions')
+        return 0;
+    if (a.type === 'workshop-finished')
+        return 10000;
+    if (a.type === 'instructions')
+        return a.exerciseNumber * 100;
+    if (a.type === 'step')
+        return a.exerciseNumber * 100 + a.stepNumber;
+    if (a.type === 'finished')
+        return a.exerciseNumber * 100 + 100;
+    if (a.type === 'unknown')
+        return 100000;
+    return -1;
+}
+/**
+ * Find the default playground app based on progress or next step
+ */
+async function findDefaultPlaygroundApp(params) {
+    const { exerciseStepApps, progress, authInfo, getPlaygroundAppName, isProblemApp, } = params;
+    // If authenticated, try to find the next incomplete step based on progress
+    if (authInfo) {
+        const sortedProgress = [...progress].sort((a, b) => {
+            return scoreProgress(a) - scoreProgress(b);
+        });
+        const nextProgress = sortedProgress.find((p) => !p.epicCompletedAt);
+        if (nextProgress && nextProgress.type === 'step') {
+            const app = exerciseStepApps.find((a) => a.exerciseNumber === nextProgress.exerciseNumber &&
+                a.stepNumber === nextProgress.stepNumber &&
+                a.type === 'problem');
+            if (app)
+                return app;
+        }
+    }
+    // Otherwise, find the next step from current
+    const playgroundAppName = await getPlaygroundAppName();
+    const currentIndex = exerciseStepApps.findIndex((a) => a.name === playgroundAppName);
+    return exerciseStepApps.slice(currentIndex + 1).find(isProblemApp);
+}
 async function getSavedPlaygroundEntries() {
     const { init, getApps, getAppDisplayName, getSavedPlaygrounds } = await import('@epic-web/workshop-utils/apps.server');
     const { getPreferences } = await import('@epic-web/workshop-utils/db.server');
@@ -84,62 +126,23 @@ export async function show(options = {}) {
 export async function set(options = {}) {
     const { exerciseNumber, stepNumber, type, silent = false } = options;
     try {
-        const { init, getApps, getExerciseApp, getPlaygroundAppName, isExerciseStepApp, isProblemApp, setPlayground, } = await import('@epic-web/workshop-utils/apps.server');
+        const { init, getApps, getPlaygroundAppName, isExerciseStepApp, isProblemApp, setPlayground, } = await import('@epic-web/workshop-utils/apps.server');
         const { getAuthInfo } = await import('@epic-web/workshop-utils/db.server');
         const { getProgress } = await import('@epic-web/workshop-utils/epic-api.server');
         await init();
         const authInfo = await getAuthInfo();
         // If no arguments provided, try to set based on progress or next step
         if (!exerciseNumber && !stepNumber && !type) {
-            if (authInfo) {
-                // Try to find the next incomplete step based on progress
-                const progress = await getProgress();
-                const scoreProgress = (a) => {
-                    if (a.type === 'workshop-instructions')
-                        return 0;
-                    if (a.type === 'workshop-finished')
-                        return 10000;
-                    if (a.type === 'instructions')
-                        return a.exerciseNumber * 100;
-                    if (a.type === 'step')
-                        return a.exerciseNumber * 100 + a.stepNumber;
-                    if (a.type === 'finished')
-                        return a.exerciseNumber * 100 + 100;
-                    if (a.type === 'unknown')
-                        return 100000;
-                    return -1;
-                };
-                const sortedProgress = progress.sort((a, b) => {
-                    return scoreProgress(a) - scoreProgress(b);
-                });
-                const nextProgress = sortedProgress.find((p) => !p.epicCompletedAt);
-                if (nextProgress && nextProgress.type === 'step') {
-                    const exerciseApp = await getExerciseApp({
-                        exerciseNumber: nextProgress.exerciseNumber.toString(),
-                        stepNumber: nextProgress.stepNumber.toString(),
-                        type: 'problem',
-                    });
-                    if (!exerciseApp) {
-                        throw new Error('No exercise app found');
-                    }
-                    await setPlayground(exerciseApp.fullPath);
-                    if (!silent) {
-                        console.log(chalk.green(`✅ Playground set to ${exerciseApp.exerciseNumber}.${exerciseApp.stepNumber}.${exerciseApp.type}`));
-                    }
-                    return {
-                        success: true,
-                        message: `Playground set to ${exerciseApp.exerciseNumber}.${exerciseApp.stepNumber}.${exerciseApp.type}`,
-                    };
-                }
-            }
-            // Otherwise, find the next step from current
             const apps = await getApps();
             const exerciseStepApps = apps.filter(isExerciseStepApp);
-            const playgroundAppName = await getPlaygroundAppName();
-            const currentIndex = exerciseStepApps.findIndex((a) => a.name === playgroundAppName);
-            const desiredApp = exerciseStepApps
-                .slice(currentIndex + 1)
-                .find(isProblemApp);
+            const progress = await getProgress();
+            const desiredApp = await findDefaultPlaygroundApp({
+                exerciseStepApps,
+                progress,
+                authInfo,
+                getPlaygroundAppName,
+                isProblemApp,
+            });
             if (!desiredApp) {
                 const message = 'No next problem app found. You may be at the end of the workshop!';
                 if (!silent) {
@@ -199,7 +202,8 @@ export async function set(options = {}) {
 export async function selectAndSet(options = {}) {
     const { silent = false } = options;
     try {
-        const { init, getApps, isExerciseStepApp, setPlayground } = await import('@epic-web/workshop-utils/apps.server');
+        const { init, getApps, getPlaygroundAppName, isExerciseStepApp, isProblemApp, setPlayground, } = await import('@epic-web/workshop-utils/apps.server');
+        const { getAuthInfo } = await import('@epic-web/workshop-utils/db.server');
         const { getProgress } = await import('@epic-web/workshop-utils/epic-api.server');
         await init();
         assertCanPrompt({
@@ -213,6 +217,14 @@ export async function selectAndSet(options = {}) {
         const apps = await getApps();
         const exerciseStepApps = apps.filter(isExerciseStepApp);
         const progress = await getProgress();
+        const authInfo = await getAuthInfo();
+        const defaultApp = await findDefaultPlaygroundApp({
+            exerciseStepApps,
+            progress,
+            authInfo,
+            getPlaygroundAppName,
+            isProblemApp,
+        });
         const choices = exerciseStepApps.map((app) => {
             const ex = app.exerciseNumber.toString().padStart(2, '0');
             const st = app.stepNumber.toString().padStart(2, '0');
@@ -227,12 +239,23 @@ export async function selectAndSet(options = {}) {
                 description: app.fullPath,
             };
         });
+        const orderedChoices = defaultApp
+            ? (() => {
+                const preferred = choices.find((choice) => choice.value.name === defaultApp?.name);
+                if (!preferred)
+                    return choices;
+                return [
+                    preferred,
+                    ...choices.filter((choice) => choice.value.name !== defaultApp?.name),
+                ];
+            })()
+            : choices;
         try {
             const selectedApp = await search({
                 message: 'Select an exercise step to set as playground:',
                 source: async (input) => {
                     if (!input)
-                        return choices;
+                        return orderedChoices;
                     return matchSorter(choices, input, {
                         keys: ['name', 'value.name'],
                     });

package/dist/commands/workshops.d.ts

@@ -17,6 +17,7 @@ export type WorkshopsResult = {
 };
 export type AddOptions = {
     repoName?: string;
+    repoRef?: string;
     directory?: string;
     destination?: string;
     silent?: boolean;

package/dist/commands/workshops.js

@@ -99,6 +99,19 @@ function resolvePathWithTilde(inputPath) {
     }
     return trimmed;
 }
+function parseRepoSpecifier(value) {
+    const trimmed = value.trim();
+    const hashIndex = trimmed.indexOf('#');
+    if (hashIndex === -1) {
+        return { repoName: trimmed };
+    }
+    const repoName = trimmed.slice(0, hashIndex).trim();
+    const repoRef = trimmed.slice(hashIndex + 1).trim();
+    if (!repoName || !repoRef) {
+        throw new Error('Invalid repo specifier. Use the format: <repo-name>#<tag|branch|commit>.');
+    }
+    return { repoName, repoRef };
+}
 function getGitHubHeaders() {
     const headers = {
         Accept: 'application/vnd.github.v3+json',
@@ -258,7 +271,7 @@ async function checkWorkshopAccess(workshops) {
  * This handles the actual cloning and setup logic
  */
 async function addSingleWorkshop(repoName, options) {
-    const { silent = false } = options;
+    const { silent = false, repoRef } = options;
     const hasExplicitCloneDestination = Boolean(options.destination?.trim() || options.directory?.trim());
     // Ensure config is set up first (only when using the managed repos directory)
     if (!hasExplicitCloneDestination) {
@@ -344,7 +357,8 @@ async function addSingleWorkshop(repoName, options) {
     }
     const repoUrl = `https://github.com/${GITHUB_ORG}/${repoName}.git`;
     if (!silent) {
-        console.log(chalk.cyan(`📦 Cloning ${repoUrl}...`));
+        const refHint = repoRef ? ` (${repoRef})` : '';
+        console.log(chalk.cyan(`📦 Cloning ${repoUrl}${refHint}...`));
     }
     // Clone the repository
     const cloneArgs = cloneIntoExistingDir
@@ -362,6 +376,31 @@ async function addSingleWorkshop(repoName, options) {
             error: cloneResult.error,
         };
     }
+    if (repoRef) {
+        if (!silent) {
+            console.log(chalk.cyan(`🔀 Checking out ${repoRef}...`));
+        }
+        const checkoutResult = await runCommand('git', ['checkout', repoRef], {
+            cwd: workshopPath,
+            silent,
+        });
+        if (!checkoutResult.success) {
+            if (!silent) {
+                console.log(chalk.yellow(`🧹 Cleaning up cloned directory...`));
+            }
+            try {
+                await fs.promises.rm(workshopPath, { recursive: true, force: true });
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            return {
+                success: false,
+                message: `Failed to check out ${repoRef}: ${checkoutResult.message}`,
+                error: checkoutResult.error,
+            };
+        }
+    }
     const setupResult = await setup({ cwd: workshopPath, silent });
     if (!setupResult.success) {
         // Clean up the cloned directory on setup failure
@@ -380,7 +419,8 @@ async function addSingleWorkshop(repoName, options) {
             error: setupResult.error,
         };
     }
-    const message = `Workshop "${repoName}" cloned successfully to ${workshopPath}`;
+    const refSuffix = repoRef ? ` (${repoRef})` : '';
+    const message = `Workshop "${repoName}"${refSuffix} cloned successfully to ${workshopPath}`;
     if (!silent) {
         console.log(chalk.green(`✅ ${message}`));
     }
@@ -392,6 +432,25 @@ async function addSingleWorkshop(repoName, options) {
 export async function add(options) {
     const { silent = false } = options;
     let { repoName } = options;
+    let repoRef = options.repoRef;
+    if (repoName) {
+        try {
+            const parsed = parseRepoSpecifier(repoName);
+            repoName = parsed.repoName;
+            repoRef = parsed.repoRef ?? repoRef;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (!silent) {
+                console.error(chalk.red(`❌ ${message}`));
+            }
+            return {
+                success: false,
+                message,
+                error: error instanceof Error ? error : new Error(message),
+            };
+        }
+    }
     try {
         // If no repo name provided, fetch available workshops and let user select
         if (!repoName) {
@@ -406,6 +465,7 @@ export async function add(options) {
                 hints: [
                     'Provide the repo name: npx epicshop add <repo-name>',
                     'Example: npx epicshop add react-fundamentals',
+                    'Pin to a tag/branch/commit: npx epicshop add react-fundamentals#v1.2.0',
                 ],
             });
             const spinner = ora('Fetching available workshops...').start();
@@ -667,7 +727,10 @@ export async function add(options) {
                 for (const selectedRepo of selectedRepoNames) {
                     const displayName = getDisplayName(selectedRepo);
                     console.log(chalk.cyan(`🏎️  Setting up ${chalk.bold(displayName)}...\n`));
-                    const result = await addSingleWorkshop(selectedRepo, options);
+                    const result = await addSingleWorkshop(selectedRepo, {
+                        ...options,
+                        repoRef,
+                    });
                     if (result.success) {
                         successCount++;
                         console.log(chalk.green(`🏁 Finished setting up ${chalk.bold(displayName)}\n`));
@@ -706,7 +769,7 @@ export async function add(options) {
             }
             const displayName = getDisplayName(repoName);
             console.log(chalk.cyan(`🏎️  Setting up ${chalk.bold(displayName)}...\n`));
-            const result = await addSingleWorkshop(repoName, options);
+            const result = await addSingleWorkshop(repoName, { ...options, repoRef });
             if (result.success) {
                 console.log(chalk.green(`🏁 Finished setting up ${chalk.bold(displayName)}\n`));
                 console.log(chalk.white('Run:'));
@@ -724,7 +787,7 @@ export async function add(options) {
         if (!silent) {
             console.log(chalk.cyan(`🏎️  Setting up ${chalk.bold(repoName)}...\n`));
         }
-        const result = await addSingleWorkshop(repoName, options);
+        const result = await addSingleWorkshop(repoName, { ...options, repoRef });
         if (result.success && !silent) {
             console.log(chalk.green(`🏁 Finished setting up ${chalk.bold(repoName)}\n`));
             console.log(chalk.white('Run:'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "epicshop",
-  "version": "6.74.3",
+  "version": "6.75.1",
   "publishConfig": {
     "access": "public"
   },
@@ -99,7 +99,7 @@
     "build:watch": "nx watch --projects=epicshop -- nx run \\$NX_PROJECT_NAME:build"
   },
   "dependencies": {
-    "@epic-web/workshop-utils": "6.74.3",
+    "@epic-web/workshop-utils": "6.75.1",
     "@inquirer/prompts": "^8.2.0",
     "@sentry/node": "^10.36.0",
     "chalk": "^5.6.2",