epicshop 6.74.2 → 6.75.0

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({

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.2",
+  "version": "6.75.0",
   "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.2",
+    "@epic-web/workshop-utils": "6.75.0",
     "@inquirer/prompts": "^8.2.0",
     "@sentry/node": "^10.36.0",
     "chalk": "^5.6.2",