@epic-web/workshop-utils 6.61.3 → 6.62.0

package/dist/apps.server.d.ts

@@ -472,7 +472,7 @@ declare const SolutionAppSchema: z.ZodObject<{
     instructionsCode?: string | undefined;
     epicVideoEmbeds?: string[] | undefined;
 }>;
-declare const ExampleAppSchema: z.ZodObject<{
+declare const ExtraAppSchema: z.ZodObject<{
     /** a unique identifier for the app */
     name: z.ZodString;
     /** the title of the app used for display (comes from the package.json title prop) */
@@ -550,7 +550,7 @@ declare const ExampleAppSchema: z.ZodObject<{
     }>]>;
     stackBlitzUrl: z.ZodNullable<z.ZodString>;
 } & {
-    type: z.ZodLiteral<"example">;
+    type: z.ZodLiteral<"extra">;
 }, "strip", z.ZodTypeAny, {
     test: {
         type: "browser";
@@ -562,7 +562,7 @@ declare const ExampleAppSchema: z.ZodObject<{
     } | {
         type: "none";
     };
-    type: "example";
+    type: "extra";
     title: string;
     name: string;
     fullPath: string;
@@ -595,7 +595,7 @@ declare const ExampleAppSchema: z.ZodObject<{
     } | {
         type: "none";
     };
-    type: "example";
+    type: "extra";
     title: string;
     name: string;
     fullPath: string;
@@ -3683,7 +3683,7 @@ declare const AppSchema: z.ZodUnion<[z.ZodUnion<[z.ZodObject<{
     }>]>;
     stackBlitzUrl: z.ZodNullable<z.ZodString>;
 } & {
-    type: z.ZodLiteral<"example">;
+    type: z.ZodLiteral<"extra">;
 }, "strip", z.ZodTypeAny, {
     test: {
         type: "browser";
@@ -3695,7 +3695,7 @@ declare const AppSchema: z.ZodUnion<[z.ZodUnion<[z.ZodObject<{
     } | {
         type: "none";
     };
-    type: "example";
+    type: "extra";
     title: string;
     name: string;
     fullPath: string;
@@ -3728,7 +3728,7 @@ declare const AppSchema: z.ZodUnion<[z.ZodUnion<[z.ZodObject<{
     } | {
         type: "none";
     };
-    type: "example";
+    type: "extra";
     title: string;
     name: string;
     fullPath: string;
@@ -3754,7 +3754,7 @@ declare const AppSchema: z.ZodUnion<[z.ZodUnion<[z.ZodObject<{
 export type BaseExerciseStepApp = z.infer<typeof BaseExerciseStepAppSchema>;
 export type ProblemApp = z.infer<typeof ProblemAppSchema>;
 export type SolutionApp = z.infer<typeof SolutionAppSchema>;
-export type ExampleApp = z.infer<typeof ExampleAppSchema>;
+export type ExtraApp = z.infer<typeof ExtraAppSchema>;
 export type PlaygroundApp = z.infer<typeof PlaygroundAppSchema>;
 export type ExerciseStepApp = z.infer<typeof ExerciseStepAppSchema>;
 export type App = z.infer<typeof AppSchema>;
@@ -3770,7 +3770,7 @@ export declare function isFirstStepSolutionApp(app: App): app is SolutionApp & {
     stepNumber: 1;
 };
 export declare function isPlaygroundApp(app: any): app is PlaygroundApp;
-export declare function isExampleApp(app: any): app is ExampleApp;
+export declare function isExtraApp(app: any): app is ExtraApp;
 export declare function isExerciseStepApp(app: any): app is ExerciseStepApp;
 export declare const modifiedTimes: Map<string, number>;
 export declare function init(workshopRoot?: string): Promise<void>;
@@ -4518,7 +4518,7 @@ export declare function getAppByName(name: string, { request, timings }?: Cachif
     } | {
         type: "none";
     };
-    type: "example";
+    type: "extra";
     title: string;
     name: string;
     fullPath: string;
@@ -4812,7 +4812,7 @@ export declare function getAppFromFile(filePath: string): Promise<{
     } | {
         type: "none";
     };
-    type: "example";
+    type: "extra";
     title: string;
     name: string;
     fullPath: string;
@@ -4903,7 +4903,7 @@ export declare function getWorkshopInstructions({ request, }?: {
     readonly file: string;
     readonly relativePath: "exercises";
 }>;
-export declare function getExamplesInstructions({ request, }?: {
+export declare function getExtrasInstructions({ request, }?: {
     request?: Request;
 }): Promise<{
     readonly compiled: {
@@ -4916,7 +4916,7 @@ export declare function getExamplesInstructions({ request, }?: {
         readonly error: string;
     };
     readonly file: string;
-    readonly relativePath: "examples/README.mdx";
+    readonly relativePath: "extra/README.mdx" | "example/README.mdx" | "examples/README.mdx";
 }>;
 export declare function getWorkshopFinished({ request, }?: {
     request?: Request;

package/dist/apps.server.js

@@ -12,7 +12,7 @@ import { execa } from 'execa';
 import fsExtra from 'fs-extra';
 import { globby, isGitIgnored } from 'globby';
 import { z } from 'zod';
-import { cachified, exampleAppCache, playgroundAppCache, problemAppCache, solutionAppCache, directoryEmptyCache, } from "./cache.server.js";
+import { cachified, extraAppCache, playgroundAppCache, problemAppCache, solutionAppCache, directoryEmptyCache, } from "./cache.server.js";
 import { compileMdx } from "./compile-mdx.server.js";
 import { getAppConfig, getStackBlitzUrl } from "./config.server.js";
 import { getPreferences } from "./db.server.js";
@@ -24,6 +24,57 @@ import { getServerTimeHeader, time } from "./timing.server.js";
 import { dayjs } from "./utils.server.js";
 import { getErrorMessage } from "./utils.js";
 const log = logger('epic:apps');
+const EXTRA_DIRNAME = 'extra';
+const LEGACY_EXAMPLE_DIRNAME = 'example';
+const LEGACY_EXAMPLES_DIRNAME = 'examples';
+const EXTRA_DIR_CANDIDATES = [
+    EXTRA_DIRNAME,
+    LEGACY_EXAMPLE_DIRNAME,
+    LEGACY_EXAMPLES_DIRNAME,
+];
+async function resolveExtraDir() {
+    for (const dirName of EXTRA_DIR_CANDIDATES) {
+        const fullPath = path.join(getWorkshopRoot(), dirName);
+        if (await exists(fullPath)) {
+            return { dirName, fullPath };
+        }
+    }
+    return null;
+}
+async function getExtraDirName() {
+    const resolved = await resolveExtraDir();
+    return resolved?.dirName ?? EXTRA_DIRNAME;
+}
+function getExtraDirInfoFromPath(fullPath) {
+    const normalizedFullPath = fullPath.replace(/\\/g, '/');
+    const normalizedRoot = getWorkshopRoot().replace(/\\/g, '/');
+    for (const dirName of EXTRA_DIR_CANDIDATES) {
+        const prefix = `${normalizedRoot}/${dirName}/`;
+        if (normalizedFullPath.startsWith(prefix)) {
+            return {
+                dirName,
+                restOfPath: normalizedFullPath.slice(prefix.length),
+            };
+        }
+    }
+    return null;
+}
+function parseExtraAppName(appName) {
+    const prefixes = ['extra.', '.extra', 'example.', '.example'];
+    for (const prefix of prefixes) {
+        if (appName.startsWith(prefix)) {
+            let relativePath = appName.slice(prefix.length);
+            // Only strip the leading dot if the prefix didn't end with a dot
+            // (i.e., for .extra and .example, not for extra. and example.)
+            // This preserves hidden directories like .my-hidden-app
+            if (!prefix.endsWith('.') && relativePath.startsWith('.')) {
+                relativePath = relativePath.slice(1);
+            }
+            return relativePath.length ? relativePath : null;
+        }
+    }
+    return null;
+}
 global.__epicshop_apps_initialized__ ??= false;
 export function setWorkshopRoot(root = process.env.EPICSHOP_CONTEXT_CWD ?? process.cwd()) {
     process.env.EPICSHOP_CONTEXT_CWD = root;
@@ -83,8 +134,8 @@ const SolutionAppSchema = BaseExerciseStepAppSchema.extend({
     type: z.literal('solution'),
     problemName: z.string().nullable(),
 });
-const ExampleAppSchema = BaseAppSchema.extend({
-    type: z.literal('example'),
+const ExtraAppSchema = BaseAppSchema.extend({
+    type: z.literal('extra'),
 });
 const PlaygroundAppSchema = BaseAppSchema.extend({
     type: z.literal('playground'),
@@ -131,7 +182,7 @@ const ExerciseStepAppSchema = z.union([ProblemAppSchema, SolutionAppSchema]);
 const AppSchema = z.union([
     ExerciseStepAppSchema,
     PlaygroundAppSchema,
-    ExampleAppSchema,
+    ExtraAppSchema,
 ]);
 export function isApp(app) {
     return AppSchema.safeParse(app).success;
@@ -151,8 +202,8 @@ export function isFirstStepSolutionApp(app) {
 export function isPlaygroundApp(app) {
     return isApp(app) && app.type === 'playground';
 }
-export function isExampleApp(app) {
-    return isApp(app) && app.type === 'example';
+export function isExtraApp(app) {
+    return isApp(app) && app.type === 'extra';
 }
 export function isExerciseStepApp(app) {
     return isProblemApp(app) || isSolutionApp(app);
@@ -196,9 +247,10 @@ export async function init(workshopRoot) {
     if (!getEnv().EPICSHOP_DEPLOYED &&
         process.env.EPICSHOP_ENABLE_WATCHER === 'true') {
         const isIgnored = await isGitIgnored({ cwd: getWorkshopRoot() });
+        const extraDirName = await getExtraDirName();
         // watch the README, FINISHED, and package.json for changes that affect the apps
         const filesToWatch = ['README.mdx', 'FINISHED.mdx', 'package.json'];
-        const chok = chokidar.watch(['examples', 'playground', 'exercises'], {
+        const chok = chokidar.watch([extraDirName, 'playground', 'exercises'], {
             cwd: getWorkshopRoot(),
             // we want to load up the modified times immediately
             ignoreInitial: false,
@@ -211,8 +263,11 @@ export async function init(workshopRoot) {
                     if (filePath.endsWith('playground'))
                         return false;
                     const pathParts = filePath.split(path.sep);
-                    if (pathParts.at(-2) === 'examples')
+                    const parentDir = pathParts.at(-2);
+                    if (parentDir &&
+                        EXTRA_DIR_CANDIDATES.includes(parentDir)) {
                         return false;
+                    }
                     // steps
                     if (pathParts.at(-3) === 'exercises')
                         return false;
@@ -367,7 +422,7 @@ export const getExercises = requestStorageify(_getExercises);
 async function _getApps({ timings, request, } = {}) {
     await init();
     const apps = await time(async () => {
-        const [playgroundApp, problemApps, solutionApps, exampleApps] = await Promise.all([
+        const [playgroundApp, problemApps, solutionApps, extraApps] = await Promise.all([
             time(() => getPlaygroundApp({ request, timings }), {
                 type: 'getPlaygroundApp',
                 timings,
@@ -380,8 +435,8 @@ async function _getApps({ timings, request, } = {}) {
                 type: 'getSolutionApps',
                 timings,
             }),
-            time(() => getExampleApps({ request, timings }), {
-                type: 'getExampleApps',
+            time(() => getExtraApps({ request, timings }), {
+                type: 'getExtraApps',
                 timings,
             }),
         ]);
@@ -389,7 +444,7 @@ async function _getApps({ timings, request, } = {}) {
             playgroundApp,
             ...problemApps,
             ...solutionApps,
-            ...exampleApps,
+            ...extraApps,
         ]
             .filter(Boolean)
             .sort((a, b) => {
@@ -401,13 +456,13 @@ async function _getApps({ timings, request, } = {}) {
             }
             if (isPlaygroundApp(b))
                 return 1;
-            if (isExampleApp(a)) {
-                if (isExampleApp(b))
+            if (isExtraApp(a)) {
+                if (isExtraApp(b))
                     return a.name.localeCompare(b.name);
                 else
                     return 1;
             }
-            if (isExampleApp(b))
+            if (isExtraApp(b))
                 return -1;
             if (a.type === b.type) {
                 if (a.exerciseNumber === b.exerciseNumber) {
@@ -559,9 +614,9 @@ function getPathname(fullPath) {
 function getAppName(fullPath) {
     if (/playground\/?$/.test(fullPath))
         return 'playground';
-    if (/examples\/.+\/?$/.test(fullPath)) {
-        const restOfPath = fullPath.replace(`${getWorkshopRoot()}${path.sep}examples${path.sep}`, '');
-        return `example.${restOfPath.split(path.sep).join('__sep__')}`;
+    const extraDirInfo = getExtraDirInfoFromPath(fullPath);
+    if (extraDirInfo) {
+        return `extra.${extraDirInfo.restOfPath.split('/').join('__sep__')}`;
     }
     const appIdInfo = extractNumbersAndTypeFromAppNameOrPath(fullPath);
     if (appIdInfo) {
@@ -576,12 +631,11 @@ function getAppName(fullPath) {
 export async function getFullPathFromAppName(appName) {
     if (appName === 'playground')
         return path.join(getWorkshopRoot(), 'playground');
-    if (appName.startsWith('.example')) {
-        const relativePath = appName
-            .replace('.example', '')
-            .split('__sep__')
-            .join(path.sep);
-        return path.join(getWorkshopRoot(), 'examples', relativePath);
+    const extraRelativePath = parseExtraAppName(appName);
+    if (extraRelativePath) {
+        const relativePath = extraRelativePath.split('__sep__').join(path.sep);
+        const extraDirName = await getExtraDirName();
+        return path.join(getWorkshopRoot(), extraDirName, relativePath);
     }
     if (appName.includes('__sep__')) {
         const relativePath = appName.replaceAll('__sep__', path.sep);
@@ -759,12 +813,12 @@ export async function getPlaygroundApp({ timings, request, } = {}) {
         return null;
     });
 }
-async function getExampleAppFromPath(fullPath, index, request) {
+async function getExtraAppFromPath(fullPath, index, request) {
     const dirName = path.basename(fullPath);
     const compiledReadme = await compileMdxIfExists(path.join(fullPath, 'README.mdx'), { request });
     const name = getAppName(fullPath);
     const portNumber = 8000 + index;
-    const type = 'example';
+    const type = 'extra';
     const title = compiledReadme?.title ?? name;
     return {
         name,
@@ -784,44 +838,46 @@ async function getExampleAppFromPath(fullPath, index, request) {
         }),
     };
 }
-async function getExampleApps({ timings, request, } = {}) {
-    const examplesDir = path.join(getWorkshopRoot(), 'examples');
+async function getExtraApps({ timings, request, } = {}) {
+    const extraDirInfo = await resolveExtraDir();
+    if (!extraDirInfo)
+        return [];
     // Filter to only include directories, not files like README.mdx
     const entries = await fs.promises
-        .readdir(examplesDir, { withFileTypes: true })
+        .readdir(extraDirInfo.fullPath, { withFileTypes: true })
         .catch(() => []);
-    const exampleDirs = entries
+    const extraDirs = entries
         .filter((entry) => {
         if (entry.isDirectory())
             return true;
-        log(`Skipping non-directory in examples: ${entry.name}`);
+        log(`Skipping non-directory in extras: ${entry.name}`);
         return false;
     })
-        .map((entry) => path.join(examplesDir, entry.name));
-    const exampleApps = [];
-    for (const exampleDir of exampleDirs) {
-        const index = exampleDirs.indexOf(exampleDir);
-        const key = `${exampleDir}-${index}`;
-        const exampleApp = await cachified({
+        .map((entry) => path.join(extraDirInfo.fullPath, entry.name));
+    const extraApps = [];
+    for (const extraDir of extraDirs) {
+        const index = extraDirs.indexOf(extraDir);
+        const key = `${extraDir}-${index}`;
+        const extraApp = await cachified({
             key,
-            cache: exampleAppCache,
+            cache: extraAppCache,
             ttl: 1000 * 60 * 5,
             swr: 1000 * 60 * 60 * 24 * 30,
             timings,
-            timingKey: exampleDir.replace(`${examplesDir}${path.sep}`, ''),
+            timingKey: extraDir.replace(`${extraDirInfo.fullPath}${path.sep}`, ''),
             request,
-            forceFresh: await getForceFreshForDir(exampleAppCache.get(key), exampleDir),
+            forceFresh: await getForceFreshForDir(extraAppCache.get(key), extraDir),
             getFreshValue: async () => {
-                return getExampleAppFromPath(exampleDir, index, request).catch((error) => {
+                return getExtraAppFromPath(extraDir, index, request).catch((error) => {
                     console.error(error);
                     return null;
                 });
             },
         });
-        if (exampleApp)
-            exampleApps.push(exampleApp);
+        if (extraApp)
+            extraApps.push(extraApp);
     }
-    return exampleApps;
+    return extraApps;
 }
 async function getSolutionAppFromPath(fullPath, request) {
     const dirName = path.basename(fullPath);
@@ -996,7 +1052,7 @@ export async function getExerciseApp(params, { request, timings } = {}) {
     const { type, exerciseNumber, stepNumber } = result.data;
     const apps = (await getApps({ request, timings })).filter(isExerciseStepApp);
     const exerciseApp = apps.find((app) => {
-        if (isExampleApp(app))
+        if (isExtraApp(app))
             return false;
         return (app.exerciseNumber === exerciseNumber &&
             app.stepNumber === stepNumber &&
@@ -1009,7 +1065,24 @@ export async function getExerciseApp(params, { request, timings } = {}) {
 }
 export async function getAppByName(name, { request, timings } = {}) {
     const apps = await getApps({ request, timings });
-    return apps.find((a) => a.name === name);
+    // First try exact match
+    const exactMatch = apps.find((a) => a.name === name);
+    if (exactMatch)
+        return exactMatch;
+    // For backward compatibility, check if this is a legacy app name
+    // (e.g., example.my-app) and find the corresponding extra app (extra.my-app)
+    const relativePath = parseExtraAppName(name);
+    if (relativePath) {
+        // Try to find an app with the same relative path but different prefix
+        const alternativePrefixes = ['extra.', 'example.'];
+        for (const prefix of alternativePrefixes) {
+            const alternativeName = `${prefix}${relativePath.split('/').join('__sep__')}`;
+            const match = apps.find((a) => a.name === alternativeName);
+            if (match)
+                return match;
+        }
+    }
+    return undefined;
 }
 export async function getNextExerciseApp(app, { request, timings } = {}) {
     const apps = (await getApps({ request, timings })).filter(isExerciseStepApp);
@@ -1271,8 +1344,8 @@ export function getAppDisplayName(a, allApps) {
             displayName = `🛝 ${a.appName}`;
         }
     }
-    else if (isExampleApp(a)) {
-        displayName = `📚 ${a.title} (example)`;
+    else if (isExtraApp(a)) {
+        displayName = `📚 ${a.title} (extra)`;
     }
     return displayName;
 }
@@ -1284,16 +1357,18 @@ export async function getWorkshopInstructions({ request, } = {}) {
     });
     return { compiled, file: readmeFilepath, relativePath: 'exercises' };
 }
-export async function getExamplesInstructions({ request, } = {}) {
-    const readmeFilepath = path.join(getWorkshopRoot(), 'examples', 'README.mdx');
+export async function getExtrasInstructions({ request, } = {}) {
+    const extraDirInfo = await resolveExtraDir();
+    const dirName = extraDirInfo?.dirName ?? EXTRA_DIRNAME;
+    const readmeFilepath = path.join(getWorkshopRoot(), dirName, 'README.mdx');
     const compiled = await compileMdx(readmeFilepath, { request }).then((r) => ({ ...r, status: 'success' }), (e) => {
-        console.error(`There was an error compiling the examples README.mdx`, readmeFilepath, e);
+        console.error(`There was an error compiling the extras README.mdx`, readmeFilepath, e);
         return { status: 'error', error: getErrorMessage(e) };
     });
     return {
         compiled,
         file: readmeFilepath,
-        relativePath: 'examples/README.mdx',
+        relativePath: `${dirName}/README.mdx`,
     };
 }
 export async function getWorkshopFinished({ request, } = {}) {
@@ -1324,16 +1399,27 @@ export function getAppPathFromFilePath(filePath) {
     if (!withinWorkshopRootHalf) {
         return null;
     }
-    const [part1, part2, part3] = withinWorkshopRootHalf
-        .split(path.sep)
-        .filter(Boolean);
+    const pathParts = withinWorkshopRootHalf.split(path.sep).filter(Boolean);
+    const part1 = pathParts[0] ?? '';
+    const part2 = pathParts[1] ?? '';
+    const part3 = pathParts[2] ?? '';
     // Check if the file is in the playground
     if (part1 === 'playground') {
         return path.join(getWorkshopRoot(), 'playground');
     }
-    // Check if the file is in an example
-    if (part1 === 'examples' && part2) {
-        return path.join(getWorkshopRoot(), 'examples', part2);
+    // Check if the file is in an extra app (or legacy examples)
+    if (part1 === EXTRA_DIRNAME ||
+        part1 === LEGACY_EXAMPLE_DIRNAME ||
+        part1 === LEGACY_EXAMPLES_DIRNAME) {
+        if (!part2)
+            return null;
+        invariant(part2.length > 0, 'Expected extra app directory name');
+        const extraRoot = part1 === EXTRA_DIRNAME
+            ? EXTRA_DIRNAME
+            : part1 === LEGACY_EXAMPLE_DIRNAME
+                ? LEGACY_EXAMPLE_DIRNAME
+                : LEGACY_EXAMPLES_DIRNAME;
+        return path.join(getWorkshopRoot(), extraRoot, part2);
     }
     // Check if the file is in an exercise
     if (part1 === 'exercises' && part2 && part3) {

package/dist/cache.server.d.ts

@@ -85,7 +85,7 @@ export declare const problemAppCache: C.Cache<{
     instructionsCode?: string | undefined;
     epicVideoEmbeds?: string[] | undefined;
 }>;
-export declare const exampleAppCache: C.Cache<{
+export declare const extraAppCache: C.Cache<{
     test: {
         type: "browser";
         pathname: string;
@@ -96,7 +96,7 @@ export declare const exampleAppCache: C.Cache<{
     } | {
         type: "none";
     };
-    type: "example";
+    type: "extra";
     title: string;
     name: string;
     fullPath: string;

package/dist/cache.server.js

@@ -164,7 +164,7 @@ export function epicCacheReporter({ formatDuration = defaultFormatDuration, perf
 }
 export const solutionAppCache = makeSingletonFsCache('SolutionAppCache');
 export const problemAppCache = makeSingletonFsCache('ProblemAppCache');
-export const exampleAppCache = makeSingletonFsCache('ExampleAppCache');
+export const extraAppCache = makeSingletonFsCache('ExtraAppCache');
 export const playgroundAppCache = makeSingletonFsCache('PlaygroundAppCache');
 export const diffCodeCache = makeSingletonFsCache('DiffCodeCache');
 export const diffFilesCache = makeSingletonFsCache('DiffFilesCache');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epic-web/workshop-utils",
-  "version": "6.61.3",
+  "version": "6.62.0",
   "publishConfig": {
     "access": "public"
   },