@scalar/cli 0.2.140 → 0.2.142

package/dist/commands/bundle/BundleCommand.js

@@ -0,0 +1,38 @@
+import { Command } from 'commander';
+import kleur from 'kleur';
+import fs from 'node:fs';
+import { useGivenFileOrConfiguration } from '../../utils/useGivenFileOrConfiguration.js';
+import { loadOpenApiFile } from '../../utils/loadOpenApiFile.js';
+
+function BundleCommand() {
+    const cmd = new Command('bundle');
+    cmd.description('Resolve all references in an OpenAPI file');
+    cmd.argument('[file]', 'file to bundle');
+    cmd.option('-o, --output <file>', 'output file');
+    cmd.action(async (fileArgument) => {
+        const { output } = cmd.opts();
+        const startTime = performance.now();
+        const file = useGivenFileOrConfiguration(fileArgument);
+        const { specification: newContent } = await loadOpenApiFile(file);
+        // Replace file content with newContent
+        const cache = [];
+        const json = JSON.stringify(newContent, (key, value) => {
+            if (typeof value === 'object' && value !== null) {
+                if (cache.indexOf(value) !== -1) {
+                    // Circular reference found, discard key
+                    return;
+                }
+                // Store value in our collection
+                cache.push(value);
+            }
+            return value;
+        }, 2);
+        fs.writeFileSync(output ?? file, json, 'utf8');
+        const endTime = performance.now();
+        console.log(kleur.green('OpenAPI Schema bundled'), kleur.grey(`in ${kleur.white(`${kleur.bold(`${Math.round(endTime - startTime)}`)} ms`)}`));
+        console.log();
+    });
+    return cmd;
+}
+
+export { BundleCommand };

package/dist/commands/format/FormatCommand.js

@@ -0,0 +1,44 @@
+import { openapi } from '@scalar/openapi-parser';
+import { Command } from 'commander';
+import kleur from 'kleur';
+import fs from 'node:fs';
+import { getFileOrUrl } from '../../utils/getFileOrUrl.js';
+import { isUrl } from '../../utils/isUrl.js';
+import { isYamlFileName } from '../../utils/isYamlFileName.js';
+import { useGivenFileOrConfiguration } from '../../utils/useGivenFileOrConfiguration.js';
+
+function FormatCommand() {
+    const cmd = new Command('format');
+    cmd.description('Format an OpenAPI file');
+    cmd.argument('[file|url]', 'File or URL to format');
+    cmd.option('-o, --output <file>', 'Output file');
+    cmd.action(async (inputArgument, { output }) => {
+        const startTime = performance.now();
+        const input = useGivenFileOrConfiguration(inputArgument);
+        const specification = await getFileOrUrl(input);
+        if (!specification) {
+            console.error(kleur.bold().red('[ERROR]'), kleur.red('Couldn’t read file.'));
+            process.exit(1);
+        }
+        const newContent = isYamlFileName(output || input)
+            ? await openapi().load(specification).toYaml()
+            : await openapi().load(specification).toJson();
+        // Replace file content with newContent
+        if (output) {
+            fs.writeFileSync(output, newContent, 'utf8');
+        }
+        else if (!isUrl(input)) {
+            fs.writeFileSync(input, newContent, 'utf8');
+        }
+        else {
+            console.error(kleur.bold().red('[ERROR]'), kleur.red('Output file is required for URLs. Try passing --output file flag.'));
+            process.exit(1);
+        }
+        const endTime = performance.now();
+        console.log(kleur.green('File formatted'), kleur.grey(`in ${kleur.white(`${kleur.bold(`${Math.round(endTime - startTime)}`)} ms`)}`));
+        console.log();
+    });
+    return cmd;
+}
+
+export { FormatCommand };

package/dist/commands/init/InitCommand.js

@@ -0,0 +1,145 @@
+import { confirm, isCancel, text, cancel } from '@clack/prompts';
+import { Command } from 'commander';
+import GithubSlugger from 'github-slugger';
+import kleur from 'kleur';
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG_FILE } from '../../utils/useGivenFileOrConfiguration.js';
+
+function InitCommand() {
+    const cmd = new Command('init');
+    cmd.description('Create a new `scalar.config.json` file to configure where your OpenAPI file is placed.');
+    cmd.option('-f, --file [file]', 'your OpenAPI file');
+    cmd.option('-s, --subdomain [url]', 'subdomain to publish on');
+    cmd.option('--force', 'override existing configuration');
+    cmd.action(async ({ file, subdomain, force }) => {
+        // Path to `scalar.config.json` file
+        const configFile = path.resolve(CONFIG_FILE);
+        let validInput;
+        let input = file;
+        const nextSteps = () => {
+            console.log('What to do next:');
+            console.log(`  ${kleur.cyan('scalar format')} ${kleur.gray('[options] [file|url]')} to format your OpenAPI file`);
+            console.log(`  ${kleur.cyan('scalar validate')} ${kleur.gray('[file|url]')} to validate your OpenAPI file`);
+            console.log(`  ${kleur.cyan('scalar bundle')} ${kleur.gray('[options] [file]')} to bundle your OpenAPI file`);
+            console.log(`  ${kleur.cyan('scalar serve')} ${kleur.gray('[options] [file|url]')} to serve your OpenAPI file`);
+            console.log();
+            console.log(kleur.white(`Run ${kleur.magenta('scalar --help')} to see all available commands.`));
+        };
+        // Handle cancel from the user
+        const handleCancel = () => {
+            cancel('Operation cancelled.');
+            nextSteps();
+            process.exit(0);
+        };
+        // Function to validate file extension
+        function isValidFile(filePath) {
+            const validExtensions = ['.json', '.yaml', '.yml'];
+            const extension = path.extname(filePath).toLowerCase();
+            return validExtensions.includes(extension);
+        }
+        // Check if `scalar.config.json` already exists
+        if (fs.existsSync(configFile)) {
+            console.log(`${kleur.green('⚠')} Found existing configuration: ${kleur.reset().green(`${CONFIG_FILE}`)}`);
+            if (force) {
+                console.log(`${kleur.green('✔')} Overwriting existing file…`);
+            }
+            const shouldOverwriteExisting = force ??
+                (await confirm({
+                    message: 'Do you want to override the file?',
+                    initialValue: false,
+                }));
+            if (isCancel(shouldOverwriteExisting)) {
+                handleCancel();
+            }
+            if (!shouldOverwriteExisting) {
+                handleCancel();
+            }
+        }
+        // New configuration object
+        const configuration = {
+            subdomain: '',
+            references: [],
+            guides: [],
+        };
+        // Subdomain
+        validInput = !!subdomain;
+        while (!validInput) {
+            const response = await text({
+                message: `What’s the name of your project? We’ll use that to create a custom subdomain for you.`,
+                validate(value) {
+                    if (value.trim().length === 0) {
+                        return `You didn’t provide a project name. Please provide a name!`;
+                    }
+                    return;
+                },
+            });
+            // TODO: Check if the subdomain is available
+            if (isCancel(response)) {
+                handleCancel();
+            }
+            else {
+                validInput = true;
+            }
+            const slugger = new GithubSlugger();
+            const slug = slugger.slug(response.toString());
+            // eslint-disable-next-line no-param-reassign
+            subdomain = `${slug}.apidocumentation.com`;
+            console.log(`${kleur.green('✔')} Subdomain: ${kleur.green(subdomain)}`);
+        }
+        configuration.subdomain = subdomain.trim();
+        // Reference
+        // Check if the file option is provided and valid
+        if (input) {
+            const validExtensions = ['.json', '.yaml', '.yml'];
+            const extension = path.extname(input).toLowerCase();
+            if (!validExtensions.includes(extension)) {
+                console.log(kleur.red('✖'), `Please enter a valid file path ${validExtensions.join(', ')}.`);
+            }
+        }
+        // Ask for the file path
+        validInput = input && isValidFile(input);
+        while (!validInput) {
+            const response = await text({
+                message: `Where is your OpenAPI file? ${kleur.reset().grey('(Add a path to the file)')}`,
+                validate(value) {
+                    if (value.length === 0) {
+                        return `Value is required!`;
+                    }
+                    return;
+                },
+            });
+            input = response;
+            if (isCancel(response)) {
+                handleCancel();
+            }
+            if (isValidFile(input)) {
+                validInput = true;
+            }
+            else {
+                console.log(kleur.red('✖'), `Invalid file extension. Expected: ${['.json', '.yaml', '.yml'].join(', ')}.`);
+            }
+        }
+        configuration.references.push({
+            name: 'API Reference',
+            path: input,
+        });
+        const content = JSON.stringify(configuration, null, 2);
+        // Create `scalar.config.json` file
+        fs.writeFileSync(configFile, content);
+        console.log(`${kleur.green('✔')} Configuration stored.`);
+        console.log();
+        console.log(`${kleur.bold().green(`${CONFIG_FILE}`)}`);
+        console.log();
+        console.log(`${kleur.grey(content
+            .split('\n')
+            .map((line) => `  ${line}`)
+            .join('\n'))}`);
+        console.log();
+        nextSteps();
+        console.log();
+    });
+    return cmd;
+}
+
+export { InitCommand };

package/dist/commands/mock/MockCommand.js

@@ -0,0 +1,124 @@
+import { serve } from '@hono/node-server';
+import { createMockServer } from '@scalar/mock-server';
+import { Command } from 'commander';
+import kleur from 'kleur';
+import { printSpecificationBanner } from '../../utils/printSpecificationBanner.js';
+import { watchFile } from '../../utils/watchFile.js';
+import { getMethodColor } from '../../utils/getMethodColor.js';
+import { useGivenFileOrConfiguration } from '../../utils/useGivenFileOrConfiguration.js';
+import { loadOpenApiFile } from '../../utils/loadOpenApiFile.js';
+
+function MockCommand() {
+    const cmd = new Command('mock');
+    cmd.description('Mock an API from an OpenAPI file');
+    cmd.argument('[file|url]', 'OpenAPI file or URL to mock the server for');
+    cmd.option('-w, --watch', 'watch the file for changes');
+    cmd.option('-o, --once', 'run the server only once and exit after that');
+    cmd.option('-p, --port <port>', 'set the HTTP port for the mock server');
+    cmd.action(async (fileArgument, { watch, once, port }) => {
+        // Server instance
+        let server;
+        // Configuration
+        const input = useGivenFileOrConfiguration(fileArgument);
+        // Load OpenAPI file
+        const result = await loadOpenApiFile(input);
+        if (!result.valid) {
+            console.warn(kleur.bold().red('[ERROR]'), kleur.red('Invalid OpenAPI specification'));
+            return;
+        }
+        printSpecificationBanner({
+            version: result.version,
+            schema: result.schema,
+        });
+        let { specification } = result;
+        // Watch OpenAPI file for changes
+        if (watch) {
+            await watchFile(input, async () => {
+                const newResult = await loadOpenApiFile(input);
+                const specificationHasChanged = newResult?.specification &&
+                    JSON.stringify(specification) !==
+                        JSON.stringify(newResult.specification);
+                if (specificationHasChanged) {
+                    console.log(kleur.bold().white('[INFO]'), kleur.grey('OpenAPI file modified'));
+                    printSpecificationBanner({
+                        version: newResult.version,
+                        schema: newResult.schema,
+                    });
+                    specification = newResult.specification;
+                    // Update mock server
+                    if (specification) {
+                        server.close();
+                        server = await bootServer({
+                            specification: specification,
+                            port,
+                        });
+                    }
+                }
+            });
+        }
+        // Show all paths from the specification
+        if (!specification) {
+            console.error(kleur.bold().yellow('[WARN]'), kleur.grey('Couldn’t find any paths in the OpenAPI file.'));
+            return;
+        }
+        printAvailablePaths(specification);
+        // Listen for requests
+        server = await bootServer({
+            specification,
+            port,
+        });
+        // Exit after the first run
+        if (once) {
+            setTimeout(() => {
+                server.close();
+            }, 2000);
+        }
+    });
+    return cmd;
+}
+async function bootServer({ specification, port, }) {
+    const app = await createMockServer({
+        specification,
+        onRequest,
+    });
+    return serve({
+        fetch: app.fetch,
+        port: port ?? 3000,
+    }, (info) => {
+        console.log(`${kleur.bold().green('➜ Mock Server')} ${kleur.white('listening on')} ${kleur.cyan(`http://localhost:${info.port}`)}`);
+        console.log();
+    });
+}
+function printAvailablePaths(specification) {
+    console.log(kleur.bold().white('Available Paths'));
+    console.log();
+    if (specification?.paths === undefined ||
+        Object.keys(specification?.paths).length === 0) {
+        console.log(kleur.bold().yellow('[WARN]'), kleur.grey('Couldn’t find any paths in the OpenAPI file.'));
+    }
+    // loop through all paths
+    for (const path in specification?.paths ?? []) {
+        if (specification?.paths?.[path] === undefined) {
+            continue;
+        }
+        // loop through all methods
+        for (const method in specification.paths[path]) {
+            // @ts-expect-error - we know that the path exists
+            if (specification.paths[path][method] === undefined) {
+                continue;
+            }
+            console.log(`${kleur
+                .bold()[getMethodColor(method)](method.toUpperCase().padEnd(6))} ${kleur.grey(`${path}`)}`);
+        }
+    }
+    console.log();
+}
+function onRequest({ context, operation, }) {
+    const { method } = context.req;
+    console.log(`${kleur
+        .bold()[getMethodColor(method)](method.toUpperCase().padEnd(6))} ${kleur.grey(`${context.req.path}`)}`, `${kleur.grey('→')} ${operation?.operationId
+        ? kleur.white(operation.operationId)
+        : kleur.red('[ERROR] 404 Not Found')}`);
+}
+
+export { MockCommand };

package/dist/commands/serve/ServeCommand.js

@@ -0,0 +1,89 @@
+import { serve } from '@hono/node-server';
+import { Command } from 'commander';
+import { Hono } from 'hono';
+import { stream } from 'hono/streaming';
+import kleur from 'kleur';
+import { printSpecificationBanner } from '../../utils/printSpecificationBanner.js';
+import { getHtmlDocument } from '../../utils/getHtmlDocument.js';
+import { useGivenFileOrConfiguration } from '../../utils/useGivenFileOrConfiguration.js';
+import { loadOpenApiFile } from '../../utils/loadOpenApiFile.js';
+import { watchFile } from '../../utils/watchFile.js';
+
+function ServeCommand() {
+    const cmd = new Command('serve');
+    // Old name for the command
+    cmd.alias('reference');
+    cmd.description('Serve an API Reference from an OpenAPI file');
+    cmd.argument('[file|url]', 'OpenAPI file or URL to show the reference for');
+    cmd.option('-w, --watch', 'watch the file for changes');
+    cmd.option('-o, --once', 'run the server only once and exit after that');
+    cmd.option('-p, --port <port>', 'set the HTTP port for the API reference server');
+    cmd.action(async (inputArgument, { watch, once, port }) => {
+        const input = useGivenFileOrConfiguration(inputArgument);
+        const result = await loadOpenApiFile(input);
+        if (!result.valid) {
+            return;
+        }
+        let { specification } = result;
+        printSpecificationBanner({
+            version: result.version,
+            schema: result.schema,
+        });
+        if (specification?.paths === undefined ||
+            Object.keys(specification?.paths).length === 0) {
+            console.log(kleur.bold().yellow('[WARN]'), kleur.grey('Couldn’t find any paths in the OpenAPI file.'));
+        }
+        const app = new Hono();
+        app.get('/', (c) => {
+            return c.html(getHtmlDocument(specification ?? {}, watch));
+        });
+        app.use('/__watcher', async (c, next) => {
+            c.header('Content-Type', 'text/event-stream');
+            c.header('Cache-Control', 'no-cache');
+            c.header('Connection', 'keep-alive');
+            await next();
+        });
+        app.get('/__watcher', (c) => {
+            return stream(c, async (s) => {
+                // watch file for changes
+                if (watch) {
+                    watchFile(input, async () => {
+                        const newResult = await loadOpenApiFile(input);
+                        const specificationHasChanged = newResult?.specification &&
+                            JSON.stringify(specification) !==
+                                JSON.stringify(newResult.specification);
+                        if (specificationHasChanged) {
+                            console.log(kleur.bold().white('[INFO]'), kleur.grey('OpenAPI file modified'));
+                            printSpecificationBanner({
+                                version: newResult.version,
+                                schema: newResult.schema,
+                            });
+                            specification = newResult.specification;
+                            s.write('data: file modified\n\n');
+                        }
+                    });
+                }
+                // eslint-disable-next-line no-constant-condition
+                while (true) {
+                    await new Promise((resolve) => setTimeout(resolve, 100));
+                }
+            });
+        });
+        const server = serve({
+            fetch: app.fetch,
+            port: port ?? 3000,
+        }, (info) => {
+            console.log(`${kleur.bold().green('➜ API Reference Server')} ${kleur.white('listening on')} ${kleur.cyan(`http://localhost:${info.port}`)}`);
+            console.log();
+        });
+        // Exit after the first run
+        if (once) {
+            setTimeout(() => {
+                server.close();
+            }, 2000);
+        }
+    });
+    return cmd;
+}
+
+export { ServeCommand };

package/dist/commands/share/ShareCommand.js

@@ -0,0 +1,58 @@
+import { Command } from 'commander';
+import kleur from 'kleur';
+import { getFileOrUrl } from '../../utils/getFileOrUrl.js';
+import { useGivenFileOrConfiguration } from '../../utils/useGivenFileOrConfiguration.js';
+
+function ShareCommand() {
+    const cmd = new Command('share');
+    cmd.description('Share an OpenAPI file');
+    cmd.argument('[file]', 'file to share');
+    cmd.option('-t, --token <token>', 'pass a token to update an existing sandbox');
+    cmd.action(async (fileArgument, { token }) => {
+        const file = useGivenFileOrConfiguration(fileArgument);
+        const url = 'https://sandbox.scalar.com/api/share' + (token ? `?token=${token}` : '');
+        fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                content: await getFileOrUrl(file),
+            }),
+        })
+            .then((response) => response.json())
+            .then((data) => {
+            const { id, token: newToken } = data;
+            console.log(kleur.bold().green('Your OpenAPI file is public.'));
+            console.log();
+            console.log(`${kleur.green('➜')} ${kleur
+                .bold()
+                .white('API Reference:'.padEnd(14))} ${kleur.cyan(`https://sandbox.scalar.com/p/${id}`)}`);
+            console.log(`${kleur.grey('➜')} ${kleur
+                .bold()
+                .grey('Editor:'.padEnd(14))} ${kleur.cyan(`https://sandbox.scalar.com/e/${id}`)}`);
+            console.log();
+            console.log(`${kleur.grey('➜')} ${kleur
+                .bold()
+                .grey('OpenAPI JSON:'.padEnd(14))} ${kleur.cyan(`https://sandbox.scalar.com/files/${id}/openapi.json`)}`);
+            console.log(`${kleur.grey('➜')} ${kleur
+                .bold()
+                .grey('OpenAPI YAML:'.padEnd(14))} ${kleur.cyan(`https://sandbox.scalar.com/files/${id}/openapi.yaml`)}`);
+            console.log();
+            console.log(kleur.white('Use the token to update the existing sandbox:'));
+            console.log();
+            console.log(`${kleur.grey('$')} ${kleur.bold().white(`scalar share --token=`)}${kleur.bold().cyan(`${newToken}`)} `);
+            console.log();
+        })
+            .catch((error) => {
+            console.error('Failed to share the file.');
+            console.log();
+            console.error('Error:', error);
+            console.log();
+            process.exit(1);
+        });
+    });
+    return cmd;
+}
+
+export { ShareCommand };

package/dist/commands/validate/ValidateCommand.js

@@ -0,0 +1,47 @@
+import { openapi } from '@scalar/openapi-parser';
+import { fetchUrls } from '@scalar/openapi-parser/plugins/fetch-urls';
+import { readFiles } from '@scalar/openapi-parser/plugins/read-files';
+import { Command } from 'commander';
+import kleur from 'kleur';
+import prettyjson from 'prettyjson';
+import { useGivenFileOrConfiguration } from '../../utils/useGivenFileOrConfiguration.js';
+
+/**
+ * Validate an OpenAPI file against the OpenAPI specifications
+ */
+function ValidateCommand() {
+    const cmd = new Command('validate');
+    cmd.description('Validate an OpenAPI file');
+    cmd.argument('[file|url]', 'File or URL to validate');
+    cmd.action(async (inputArgument) => {
+        const startTime = performance.now();
+        // Read file
+        const input = useGivenFileOrConfiguration(inputArgument);
+        // Validate
+        const result = await openapi()
+            .load(input, {
+            plugins: [fetchUrls(), readFiles()],
+        })
+            .validate()
+            .get();
+        if (result.valid && result.version) {
+            console.log(kleur.green(`Matches the OpenAPI specification${kleur.white(` (OpenAPI ${kleur.bold(result.version)})`)}`));
+            const endTime = performance.now();
+            console.log();
+            console.log(kleur.green('File validated'), kleur.grey(`in ${kleur.white(`${kleur.bold(`${Math.round(endTime - startTime)}`)} ms`)}`));
+            console.log();
+        }
+        else {
+            console.log(prettyjson.render(result.errors));
+            console.log();
+            console.error(kleur.red('File doesn’t match the OpenAPI specification.'));
+            console.log();
+            console.error(kleur.red(`${kleur.bold(`${result.errors?.length} error${result.errors && result.errors.length > 1 ? 's' : ''}`)} found.`));
+            console.log();
+            process.exit(1);
+        }
+    });
+    return cmd;
+}
+
+export { ValidateCommand };

package/dist/commands/void/VoidCommand.js

@@ -0,0 +1,38 @@
+import { serve } from '@hono/node-server';
+import { createVoidServer } from '@scalar/void-server';
+import { Command } from 'commander';
+import kleur from 'kleur';
+
+function VoidCommand() {
+    const cmd = new Command('void');
+    cmd.description('Boot a server to mirror HTTP requests');
+    cmd.option('-o, --once', 'run the server only once and exit after that');
+    cmd.option('-p, --port <port>', 'set the HTTP port for the mock server');
+    cmd.action(async ({ once, port, }) => {
+        // Server instance
+        let server = undefined;
+        // Listen for requests
+        server = await bootServer({
+            port,
+        });
+        // Exit after the first run
+        if (once) {
+            setTimeout(() => {
+                server.close();
+            }, 2000);
+        }
+    });
+    return cmd;
+}
+async function bootServer({ port }) {
+    const app = await createVoidServer();
+    return serve({
+        fetch: app.fetch,
+        port: port ?? 3000,
+    }, (info) => {
+        console.log(`${kleur.bold().green('➜ Void Server')} ${kleur.white('listening on')} ${kleur.cyan(`http://localhost:${info.port}`)}`);
+        console.log();
+    });
+}
+
+export { VoidCommand };