epicshop 6.50.1 → 6.50.3

package/README.md

@@ -47,6 +47,10 @@ epicshop start <workshop>
 - `epicshop open`: open a workshop in your editor
 - `epicshop update`: pull the latest workshop changes
 - `epicshop warm`: warm caches for faster workshop startup
+- `epicshop exercises`: list exercises with progress (context-aware)
+- `epicshop playground`: view or set the current playground (context-aware)
+- `epicshop progress`: view or update your progress (context-aware)
+- `epicshop diff`: show diff between playground and solution (context-aware)
 
 ## Environment variables
 
@@ -62,6 +66,14 @@ This package also exports ESM entrypoints:
 import { start } from 'epicshop/start'
 import { update } from 'epicshop/update'
 import { warm } from 'epicshop/warm'
+import { show, set } from 'epicshop/playground'
+import {
+	show as showProgress,
+	update as updateProgress,
+} from 'epicshop/progress'
+import { showProgressDiff, showDiffBetweenApps } from 'epicshop/diff'
+import { list, showExercise } from 'epicshop/exercises'
+import { status, login, logout } from 'epicshop/auth'
 ```
 
 ## Documentation

package/dist/cli.js

@@ -636,6 +636,309 @@ const cli = yargs(args)
     if (!result.success) {
         process.exit(1);
     }
+})
+    .command('playground [subcommand] [target]', 'Manage the playground environment (context-aware)', (yargs) => {
+    return yargs
+        .positional('subcommand', {
+        describe: 'Playground subcommand (show, set)',
+        type: 'string',
+        choices: ['show', 'set'],
+    })
+        .positional('target', {
+        describe: 'Target exercise step (e.g., 1.2.problem, 2.3.solution)',
+        type: 'string',
+    })
+        .option('exercise', {
+        alias: 'e',
+        type: 'number',
+        description: 'Exercise number',
+    })
+        .option('step', {
+        type: 'number',
+        description: 'Step number',
+    })
+        .option('type', {
+        alias: 't',
+        type: 'string',
+        choices: ['problem', 'solution'],
+        description: 'App type (problem or solution)',
+    })
+        .option('silent', {
+        alias: 's',
+        type: 'boolean',
+        description: 'Run without output logs',
+        default: false,
+    })
+        .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 1.2.problem', 'Set to specific step')
+        .example('$0 playground set --exercise 1 --step 2', 'Set with options');
+}, async (argv) => {
+    const { findWorkshopRoot } = await import("./commands/workshops.js");
+    const workshopRoot = await findWorkshopRoot();
+    if (!workshopRoot) {
+        console.error(chalk.red('❌ Not inside a workshop directory. Please cd into a workshop first.'));
+        process.exit(1);
+    }
+    const originalCwd = process.cwd();
+    process.chdir(workshopRoot);
+    try {
+        const { show, set, selectAndSet, parseAppIdentifier } = await import("./commands/playground.js");
+        const subcommand = argv.subcommand || 'show';
+        if (subcommand === 'show') {
+            const result = await show({ silent: argv.silent });
+            if (!result.success)
+                process.exit(1);
+        }
+        else if (subcommand === 'set') {
+            // Parse target if provided (e.g., "1.2.problem")
+            let exerciseNumber = argv.exercise;
+            let stepNumber = argv.step;
+            let type = argv.type;
+            if (argv.target) {
+                const parsed = parseAppIdentifier(argv.target);
+                // Validate that the target was parseable - at least exercise number should be found
+                if (parsed.exerciseNumber === undefined) {
+                    console.error(chalk.red(`❌ Invalid target format: "${argv.target}". Expected format like "1.2.problem" or "01.02.solution"`));
+                    process.exit(1);
+                }
+                exerciseNumber = parsed.exerciseNumber ?? exerciseNumber;
+                stepNumber = parsed.stepNumber ?? stepNumber;
+                type = parsed.type ?? type;
+            }
+            // If no specific target, check if we should show interactive or auto
+            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);
+                }
+            }
+            else {
+                const result = await set({
+                    exerciseNumber,
+                    stepNumber,
+                    type,
+                    silent: argv.silent,
+                });
+                if (!result.success)
+                    process.exit(1);
+            }
+        }
+        else {
+            console.error(chalk.red(`❌ Unknown subcommand: ${subcommand}`));
+            process.exit(1);
+        }
+    }
+    finally {
+        process.chdir(originalCwd);
+    }
+})
+    .command('progress [subcommand] [lesson-slug]', 'View and manage your progress (context-aware)', (yargs) => {
+    return yargs
+        .positional('subcommand', {
+        describe: 'Progress subcommand (show, update)',
+        type: 'string',
+        choices: ['show', 'update'],
+    })
+        .positional('lesson-slug', {
+        describe: 'Lesson slug to update (for update subcommand)',
+        type: 'string',
+    })
+        .option('complete', {
+        alias: 'c',
+        type: 'boolean',
+        description: 'Mark as complete (default: true)',
+        default: true,
+    })
+        .option('incomplete', {
+        alias: 'i',
+        type: 'boolean',
+        description: 'Mark as incomplete',
+        default: false,
+    })
+        .option('json', {
+        type: 'boolean',
+        description: 'Output as JSON',
+        default: false,
+    })
+        .option('silent', {
+        alias: 's',
+        type: 'boolean',
+        description: 'Run without output logs',
+        default: false,
+    })
+        .example('$0 progress', 'Show progress for current workshop')
+        .example('$0 progress show', 'Show progress for current workshop')
+        .example('$0 progress show --json', 'Output progress as JSON')
+        .example('$0 progress update 01-01-problem', 'Mark lesson as complete')
+        .example('$0 progress update 01-01-problem --incomplete', 'Mark lesson as incomplete');
+}, async (argv) => {
+    const { findWorkshopRoot } = await import("./commands/workshops.js");
+    const workshopRoot = await findWorkshopRoot();
+    if (!workshopRoot) {
+        console.error(chalk.red('❌ Not inside a workshop directory. Please cd into a workshop first.'));
+        process.exit(1);
+    }
+    const originalCwd = process.cwd();
+    process.chdir(workshopRoot);
+    try {
+        const { show, update } = await import("./commands/progress.js");
+        const subcommand = argv.subcommand || 'show';
+        if (subcommand === 'show') {
+            const result = await show({
+                silent: argv.silent,
+                json: argv.json,
+            });
+            if (!result.success)
+                process.exit(1);
+        }
+        else if (subcommand === 'update') {
+            // --incomplete takes precedence, otherwise use --complete value
+            const complete = argv.incomplete ? false : argv.complete;
+            const result = await update({
+                lessonSlug: argv.lessonSlug,
+                complete,
+                silent: argv.silent,
+            });
+            if (!result.success)
+                process.exit(1);
+        }
+        else {
+            console.error(chalk.red(`❌ Unknown subcommand: ${subcommand}`));
+            process.exit(1);
+        }
+    }
+    finally {
+        process.chdir(originalCwd);
+    }
+})
+    .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.',
+        type: 'string',
+    })
+        .positional('app2', {
+        describe: 'Second app identifier (e.g., 01.02.solution)',
+        type: 'string',
+    })
+        .option('silent', {
+        alias: 's',
+        type: 'boolean',
+        description: 'Run without output logs',
+        default: false,
+    })
+        .example('$0 diff', 'Show diff between playground and solution')
+        .example('$0 diff 01.02.problem 01.02.solution', 'Show diff between two apps');
+}, async (argv) => {
+    const { findWorkshopRoot } = await import("./commands/workshops.js");
+    const workshopRoot = await findWorkshopRoot();
+    if (!workshopRoot) {
+        console.error(chalk.red('❌ Not inside a workshop directory. Please cd into a workshop first.'));
+        process.exit(1);
+    }
+    const originalCwd = process.cwd();
+    process.chdir(workshopRoot);
+    try {
+        const { showProgressDiff, showDiffBetweenApps } = await import("./commands/diff.js");
+        if (argv.app1 && argv.app2) {
+            const result = await showDiffBetweenApps({
+                app1: argv.app1,
+                app2: argv.app2,
+                silent: argv.silent,
+            });
+            if (!result.success)
+                process.exit(1);
+        }
+        else if (argv.app1 && !argv.app2) {
+            console.error(chalk.red('❌ When providing app1, app2 is also required'));
+            process.exit(1);
+        }
+        else {
+            const result = await showProgressDiff({ silent: argv.silent });
+            if (!result.success)
+                process.exit(1);
+        }
+    }
+    finally {
+        process.chdir(originalCwd);
+    }
+})
+    .command('exercises [exercise] [step]', 'List exercises or show exercise details (context-aware)', (yargs) => {
+    return yargs
+        .positional('exercise', {
+        describe: 'Exercise number to show details for (e.g., 1 or 01)',
+        type: 'string',
+    })
+        .positional('step', {
+        describe: 'Step number to show details for (e.g., 2 or 02)',
+        type: 'string',
+    })
+        .option('json', {
+        type: 'boolean',
+        description: 'Output as JSON',
+        default: false,
+    })
+        .option('silent', {
+        alias: 's',
+        type: 'boolean',
+        description: 'Run without output logs',
+        default: false,
+    })
+        .example('$0 exercises', 'List all exercises with progress')
+        .example('$0 exercises 1', 'Show details for exercise 1')
+        .example('$0 exercises 1 2', 'Show details for exercise 1 step 2')
+        .example('$0 exercises --json', 'Output exercises as JSON');
+}, async (argv) => {
+    const { findWorkshopRoot } = await import("./commands/workshops.js");
+    const workshopRoot = await findWorkshopRoot();
+    if (!workshopRoot) {
+        console.error(chalk.red('❌ Not inside a workshop directory. Please cd into a workshop first.'));
+        process.exit(1);
+    }
+    const originalCwd = process.cwd();
+    process.chdir(workshopRoot);
+    try {
+        const { list, showExercise } = await import("./commands/exercises.js");
+        if (argv.exercise) {
+            const exerciseNumber = parseInt(argv.exercise, 10);
+            if (isNaN(exerciseNumber)) {
+                console.error(chalk.red(`❌ Invalid exercise number: "${argv.exercise}". Expected a number.`));
+                process.exit(1);
+            }
+            const stepNumber = argv.step ? parseInt(argv.step, 10) : undefined;
+            if (stepNumber !== undefined && isNaN(stepNumber)) {
+                console.error(chalk.red(`❌ Invalid step number: "${argv.step}". Expected a number.`));
+                process.exit(1);
+            }
+            const result = await showExercise({
+                exerciseNumber,
+                stepNumber,
+                json: argv.json,
+                silent: argv.silent,
+            });
+            if (!result.success)
+                process.exit(1);
+        }
+        else {
+            const result = await list({
+                json: argv.json,
+                silent: argv.silent,
+            });
+            if (!result.success)
+                process.exit(1);
+        }
+    }
+    finally {
+        process.chdir(originalCwd);
+    }
 })
     .epilogue(`For more information, visit: ${chalk.cyan('https://github.com/epicweb-dev/epicshop')}`)
     .strict()
@@ -674,73 +977,86 @@ try {
             ],
         });
         const { search } = await import('@inquirer/prompts');
-        const baseChoices = [
-            {
-                name: `${chalk.green('start')} - Start a workshop`,
-                value: 'start',
-                description: workshopTitle
-                    ? `Start ${workshopTitle}`
-                    : 'Select a workshop to start',
-            },
-            {
-                name: `${chalk.green('open')} - Open a workshop in editor`,
-                value: 'open',
-                description: workshopTitle
-                    ? `Open ${workshopTitle}`
-                    : 'Select a workshop to open',
-            },
-            {
-                name: `${chalk.green('list')} - List all workshops`,
-                value: 'list',
-                description: 'List all added workshops',
-            },
-            {
-                name: `${chalk.green('add')} - Add a workshop`,
-                value: 'add',
-                description: 'Clone a workshop from epicweb-dev GitHub org',
-            },
-            {
-                name: `${chalk.green('remove')} - Remove a workshop`,
-                value: 'remove',
-                description: workshopTitle
-                    ? `Remove ${workshopTitle}`
-                    : 'Select a workshop to remove',
-            },
-            {
-                name: `${chalk.green('update')} - Update workshop`,
-                value: 'update',
-                description: workshopTitle
-                    ? `Update ${workshopTitle}`
-                    : 'Select a workshop to update',
-            },
-            {
-                name: `${chalk.green('warm')} - Warm caches`,
-                value: 'warm',
-                description: workshopTitle
-                    ? `Warm the cache for ${workshopTitle}`
-                    : 'Select a workshop to warm the cache for',
-            },
-            {
-                name: `${chalk.green('config')} - View/update configuration`,
-                value: 'config',
-                description: 'View or update workshop configuration',
-            },
-            {
-                name: `${chalk.green('init')} - First-time setup`,
-                value: 'init',
-                description: 'Initialize epicshop and start the tutorial',
-            },
-            {
-                name: `${chalk.green('auth')} - Manage authentication`,
-                value: 'auth',
-                description: 'Login/logout from EpicWeb.dev, EpicReact.dev, EpicAI.pro',
-            },
-            {
-                name: `${chalk.green('help')} - Show help`,
-                value: 'help',
-                description: 'Display CLI help information',
-            },
-        ];
+        // Build choices - workshop-specific commands only show when inside a workshop
+        const baseChoices = [];
+        // Always-available commands
+        baseChoices.push({
+            name: `${chalk.green('start')} - Start a workshop`,
+            value: 'start',
+            description: workshopTitle
+                ? `Start ${workshopTitle}`
+                : 'Select a workshop to start',
+        }, {
+            name: `${chalk.green('open')} - Open a workshop in editor`,
+            value: 'open',
+            description: workshopTitle
+                ? `Open ${workshopTitle}`
+                : 'Select a workshop to open',
+        });
+        // Workshop-specific commands (only when inside a workshop)
+        if (workshopTitle) {
+            baseChoices.push({
+                name: `${chalk.green('exercises')} - List exercises`,
+                value: 'exercises',
+                description: `View exercises and progress in ${workshopTitle}`,
+            }, {
+                name: `${chalk.green('playground')} - Manage playground`,
+                value: 'playground',
+                description: 'View or set the current playground',
+            }, {
+                name: `${chalk.green('progress')} - View/update progress`,
+                value: 'progress',
+                description: 'View or update your learning progress',
+            }, {
+                name: `${chalk.green('diff')} - Show differences`,
+                value: 'diff',
+                description: 'Show diff between playground and solution',
+            });
+        }
+        // More always-available commands
+        baseChoices.push({
+            name: `${chalk.green('list')} - List all workshops`,
+            value: 'list',
+            description: 'List all added workshops',
+        }, {
+            name: `${chalk.green('add')} - Add a workshop`,
+            value: 'add',
+            description: 'Clone a workshop from epicweb-dev GitHub org',
+        }, {
+            name: `${chalk.green('remove')} - Remove a workshop`,
+            value: 'remove',
+            description: workshopTitle
+                ? `Remove ${workshopTitle}`
+                : 'Select a workshop to remove',
+        }, {
+            name: `${chalk.green('update')} - Update workshop`,
+            value: 'update',
+            description: workshopTitle
+                ? `Update ${workshopTitle}`
+                : 'Select a workshop to update',
+        }, {
+            name: `${chalk.green('warm')} - Warm caches`,
+            value: 'warm',
+            description: workshopTitle
+                ? `Warm the cache for ${workshopTitle}`
+                : 'Select a workshop to warm the cache for',
+        }, {
+            name: `${chalk.green('config')} - View/update configuration`,
+            value: 'config',
+            description: 'View or update workshop configuration',
+        }, {
+            name: `${chalk.green('init')} - First-time setup`,
+            value: 'init',
+            description: 'Initialize epicshop and start the tutorial',
+        }, {
+            name: `${chalk.green('auth')} - Manage authentication`,
+            value: 'auth',
+            description: 'Login/logout from EpicWeb.dev, EpicReact.dev, EpicAI.pro',
+        }, {
+            name: `${chalk.green('help')} - Show help`,
+            value: 'help',
+            description: 'Display CLI help information',
+        });
         const subcommand = await search({
             message: workshopTitle
                 ? `What would you like to do? ${chalk.gray(`(in ${workshopTitle})`)}`
@@ -1006,6 +1322,86 @@ try {
                     process.exit(1);
                 break;
             }
+            case 'exercises': {
+                const { findWorkshopRoot } = await import("./commands/workshops.js");
+                const wsRoot = await findWorkshopRoot();
+                if (!wsRoot) {
+                    console.error(chalk.red('❌ Not inside a workshop directory'));
+                    process.exit(1);
+                }
+                const originalCwd = process.cwd();
+                process.chdir(wsRoot);
+                try {
+                    const { list: listExercises } = await import("./commands/exercises.js");
+                    const result = await listExercises({});
+                    if (!result.success)
+                        process.exit(1);
+                }
+                finally {
+                    process.chdir(originalCwd);
+                }
+                break;
+            }
+            case 'playground': {
+                const { findWorkshopRoot } = await import("./commands/workshops.js");
+                const wsRoot = await findWorkshopRoot();
+                if (!wsRoot) {
+                    console.error(chalk.red('❌ Not inside a workshop directory'));
+                    process.exit(1);
+                }
+                const originalCwd = process.cwd();
+                process.chdir(wsRoot);
+                try {
+                    const { show: showPlayground } = await import("./commands/playground.js");
+                    const result = await showPlayground({});
+                    if (!result.success)
+                        process.exit(1);
+                }
+                finally {
+                    process.chdir(originalCwd);
+                }
+                break;
+            }
+            case 'progress': {
+                const { findWorkshopRoot } = await import("./commands/workshops.js");
+                const wsRoot = await findWorkshopRoot();
+                if (!wsRoot) {
+                    console.error(chalk.red('❌ Not inside a workshop directory'));
+                    process.exit(1);
+                }
+                const originalCwd = process.cwd();
+                process.chdir(wsRoot);
+                try {
+                    const { show: showProgress } = await import("./commands/progress.js");
+                    const result = await showProgress({});
+                    if (!result.success)
+                        process.exit(1);
+                }
+                finally {
+                    process.chdir(originalCwd);
+                }
+                break;
+            }
+            case 'diff': {
+                const { findWorkshopRoot } = await import("./commands/workshops.js");
+                const wsRoot = await findWorkshopRoot();
+                if (!wsRoot) {
+                    console.error(chalk.red('❌ Not inside a workshop directory'));
+                    process.exit(1);
+                }
+                const originalCwd = process.cwd();
+                process.chdir(wsRoot);
+                try {
+                    const { showProgressDiff } = await import("./commands/diff.js");
+                    const result = await showProgressDiff({});
+                    if (!result.success)
+                        process.exit(1);
+                }
+                finally {
+                    process.chdir(originalCwd);
+                }
+                break;
+            }
             case 'help': {
                 cli.showHelp((helpText) => {
                     console.log(formatHelp(helpText));

package/dist/commands/diff.d.ts

@@ -0,0 +1,21 @@
+export type DiffResult = {
+    success: boolean;
+    message?: string;
+    diff?: string;
+    error?: Error;
+};
+export type DiffOptions = {
+    app1?: string;
+    app2?: string;
+    silent?: boolean;
+};
+/**
+ * Show diff between the current playground and its solution
+ */
+export declare function showProgressDiff(options?: {
+    silent?: boolean;
+}): Promise<DiffResult>;
+/**
+ * Show diff between two specific apps
+ */
+export declare function showDiffBetweenApps(options?: DiffOptions): Promise<DiffResult>;