@scalar/cli 2.0.1 → 2.5.1

package/README.md

@@ -171,18 +171,18 @@ Options:
 
 Commands:
   bundle [options] [file|url]    Bundle an OpenAPI document by resolving all references and external dependencies
-  split [options] [file|url]     Split your OpenAPI documents on small chunks
-  join [options] <files...>      Merge multiple OpenAPI documents into a single unified document
-  format [options] [file|url]    Format an OpenAPI file
+  split [options] [file|url]     Split OpenAPI or AsyncAPI documents into small chunks
+  join [options] <files...>      Merge multiple OpenAPI or AsyncAPI documents into a single unified document
+  format [options] [file|url]    Format an OpenAPI or AsyncAPI file
   convert [options] [file|url]   Convert a Postman collection to an OpenAPI document
   markdown [options] [file|url]  Generate Markdown from an OpenAPI file
-  mock [options] [file|url]      Mock an API from an OpenAPI file
-  serve [options] [file|url]     Serve an API Reference from an OpenAPI file
-  share [options] [file]         Share an OpenAPI file
-  validate [file|url]            Validate an OpenAPI file
+  mock [options] [file|url]      Mock an OpenAPI API or AsyncAPI WebSocket and SSE channels
+  serve [options] [file|url]     Serve an API Reference from an OpenAPI or AsyncAPI file
+  share [options] [file]         Share an OpenAPI or AsyncAPI file
+  validate [file|url]            Validate an OpenAPI or AsyncAPI file
   void [options]                 Boot a server to mirror HTTP requests
-  lint [options] [file|url]      Lint your OpenAPI file using spectral rules
-  upgrade [options] [file|url]   Upgrade OpenAPI document to version 3.1
+  lint [options] [file|url]      Lint your OpenAPI or AsyncAPI file using spectral rules
+  upgrade [options] [file|url]   Upgrade an OpenAPI or AsyncAPI document to version 3.1
   help [command]                 display help for command
 ```
 
@@ -204,13 +204,16 @@ Options:
 ```
 
 #### split
+
+Splits AsyncAPI channels, operations, messages, and reusable components (including payload schemas) into JSON chunks. AsyncAPI versions are preserved, including 2.6, 3.0, and 3.1; splitting does not upgrade the document or add Scalar navigation metadata. Use `scalar document upgrade` separately to normalize versions. Nested external references are bundled relative to their source files or URLs, and chunk references resolve relative to the generated files. Both relative and absolute output directories are supported. The entry point is `out.json`.
+
 ```
 Usage: scalar document split [options] [file|url]
 
-Split your OpenAPI documents on small chunks
+Split OpenAPI or AsyncAPI documents into small chunks
 
 Arguments:
-  file|url             Path to OpenAPI file or URL to split
+  file|url             Path to OpenAPI or AsyncAPI file or URL to split
 
 Options:
   -o, --output <path>  Path to save the chunks
@@ -221,10 +224,10 @@ Options:
 ```
 Usage: scalar document join [options] <files...>
 
-Merge multiple OpenAPI documents into a single unified document
+Merge multiple OpenAPI or AsyncAPI documents into a single unified document
 
 Arguments:
-  files                                          Paths to the OpenAPI files to merge
+  files                                          Paths to the OpenAPI or AsyncAPI files to merge
 
 Options:
   --output -o <file>                             Path to save the merged output file
@@ -236,7 +239,7 @@ Options:
 ```
 Usage: scalar document format [options] [file|url]
 
-Format an OpenAPI file
+Format an OpenAPI or AsyncAPI file
 
 Arguments:
   file|url             File or URL to format
@@ -279,10 +282,10 @@ Options:
 ```
 Usage: scalar document mock [options] [file|url]
 
-Mock an API from an OpenAPI file
+Mock an OpenAPI API or AsyncAPI WebSocket and SSE channels
 
 Arguments:
-  file|url           OpenAPI file or URL to mock the server for
+  file|url           OpenAPI or AsyncAPI file or URL to mock
 
 Options:
   -w, --watch        watch the file for changes
@@ -295,10 +298,10 @@ Options:
 ```
 Usage: scalar document serve [options] [file|url]
 
-Serve an API Reference from an OpenAPI file
+Serve an API Reference from an OpenAPI or AsyncAPI file
 
 Arguments:
-  file|url           OpenAPI file or URL to show the reference for
+  file|url           OpenAPI or AsyncAPI file or URL to show the reference for
 
 Options:
   -w, --watch        watch the file for changes
@@ -311,7 +314,7 @@ Options:
 ```
 Usage: scalar document share [options] [file]
 
-Share an OpenAPI file
+Share an OpenAPI or AsyncAPI file
 
 Arguments:
   file                 file to share
@@ -325,7 +328,7 @@ Options:
 ```
 Usage: scalar document validate [options] [file|url]
 
-Validate an OpenAPI file
+Validate an OpenAPI or AsyncAPI file
 
 Arguments:
   file|url    File or URL to validate
@@ -350,10 +353,10 @@ Options:
 ```
 Usage: scalar document lint [options] [file|url]
 
-Lint your OpenAPI file using spectral rules
+Lint your OpenAPI or AsyncAPI file using spectral rules
 
 Arguments:
-  file|url               OpenAPI file path or url
+  file|url               OpenAPI or AsyncAPI file path or url
 
 Options:
   -r, --rule <file|url>  Rule path or url
@@ -364,10 +367,10 @@ Options:
 ```
 Usage: scalar document upgrade [options] [file|url]
 
-Upgrade OpenAPI document to version 3.1
+Upgrade an OpenAPI or AsyncAPI document to version 3.1
 
 Arguments:
-  file|url             File or URL to validate
+  file|url             File or URL to upgrade
 
 Options:
   -o, --output <file>  Path to save the upgraded output file
@@ -389,6 +392,8 @@ Commands:
   create [options]            Create a new project that is not linked to a github project.
   preview [options] [config]  Preview scalar guides
   publish [options]           Publish new build for a github sync project that is not linked.
+  rollback [options]          Roll the live deployment back to a previously deployed build.
+  deployments                 Inspect a project deployment history.
   upgrade [config]            Upgrade scalar project
   help [command]              display help for command
 ```
@@ -462,6 +467,44 @@ Options:
   -h, --help             display help for command
 ```
 
+#### rollback
+```
+Usage: scalar project rollback [options]
+
+Roll the live deployment back to a previously deployed build.
+
+Options:
+  -s, --slug [slug]      Project slug found in Scalar Dashboard
+  -t, --to <publishUid>  Roll back to a specific build id (defaults to the next older deployed build)
+  -y, --yes              Skip the confirmation prompt
+  -h, --help             display help for command
+```
+
+#### deployments
+```
+Usage: scalar project deployments [options] [command]
+
+Inspect a project deployment history.
+
+Options:
+  -h, --help      display help for command
+
+Commands:
+  list [options]  List the production deployment history for a project.
+  help [command]  display help for command
+```
+
+##### list
+```
+Usage: scalar project deployments list [options]
+
+List the production deployment history for a project.
+
+Options:
+  -s, --slug [slug]  Project slug found in Scalar Dashboard
+  -h, --help         display help for command
+```
+
 #### upgrade
 ```
 Usage: scalar project upgrade [options] [config]
@@ -779,6 +822,7 @@ Options:
   --namespace <namespace>  Scalar team namespace
   --version <version>      API version (e.g. 0.1.0)
   --private                Make API private (default: false)
+  --force                  Force override an existing version (default: false)
   --bundle                 Bundle all external references before uploading
   --treeShake              Remove unused components from the bundled document
   --urlMap                 Generate a map of resolved URLs when bundling the document

package/chunks/action-37EV4UHW.js

@@ -0,0 +1,125 @@
+import { createRequire as $$cR } from "node:module"; const require = $$cR(import.meta.url);
+import {
+  createError,
+  displayError
+} from "./chunk-3ZJYGGAA.js";
+import {
+  readAndParseConfig,
+  renderConfigError
+} from "./chunk-7AGLC7WV.js";
+import {
+  CONFIG_FILE_DEFAULT,
+  findConfig,
+  legacyTo2_0_0
+} from "./chunk-PBXZN65A.js";
+import {
+  ConfigVersion
+} from "./chunk-OQKDBLOZ.js";
+import "./chunk-K74E42RV.js";
+import "./chunk-CISTON3A.js";
+import "./chunk-Q7DOQHZN.js";
+import {
+  output
+} from "./chunk-T5HJUAWB.js";
+import "./chunk-GSGZHE26.js";
+import "./chunk-IKT5F47M.js";
+import "./chunk-3MZYUBJ6.js";
+
+// src/domains/project/upgrade/action.ts
+import fs from "node:fs/promises";
+import path from "node:path";
+import { text } from "@clack/prompts";
+import as from "ansis";
+import { n } from "neverpanic";
+async function upgradeAction(__configPath) {
+  const configPath = __configPath || findConfig() || await text({
+    message: "Where is your configuration file located?",
+    defaultValue: CONFIG_FILE_DEFAULT,
+    placeholder: CONFIG_FILE_DEFAULT
+  });
+  const parseConfigResult = readAndParseConfig(configPath);
+  if (!parseConfigResult.success) {
+    renderConfigError(parseConfigResult.error);
+  }
+  if (parseConfigResult.success) {
+    output.info().line(
+      `${as.green("[SUCCESS]")} ${as.green("Configuration is valid:")} ${as.green(parseConfigResult.filePath)}`
+    ).print();
+  }
+  const { config } = parseConfigResult;
+  if (config.version === ConfigVersion.V2) {
+    return output.info().title("Your Scalar configuration is already upgraded").message(
+      "You are already on the latest Scalar docs version. No further action required."
+    ).exit("success");
+  }
+  const upgradedConfigResult = n.fromUnsafe(
+    () => legacyTo2_0_0(config),
+    (originalError) => createError("FAILED_TO_UPGRADE_CONFIG_V1", originalError)
+  );
+  if (!upgradedConfigResult.success) {
+    return output.error().title("Could not upgrade config.").message(upgradedConfigResult.error.code).message(displayError(upgradedConfigResult.error.detail)).exit("error");
+  }
+  const { upgradedConfig, legacyTheme, legacyFooter, legacyScript } = upgradedConfigResult.data;
+  if (legacyTheme) {
+    const writeUpgradedThemeResult = await n.fromUnsafe(
+      () => fs.writeFile(
+        path.resolve(
+          path.dirname(parseConfigResult.filePath),
+          config.root ?? "./",
+          legacyTheme.path
+        ),
+        legacyTheme.cssString
+      ),
+      (originalError) => createError("FAILED_TO_WRITE_UPGRADED_THEME", originalError)
+    );
+    if (!writeUpgradedThemeResult.success) {
+      return output.error().title("Could not save upgraded theme.").message(writeUpgradedThemeResult.error.code).message(displayError(writeUpgradedThemeResult.error.detail)).exit("error");
+    }
+  }
+  if (legacyFooter) {
+    const writeUpgradedFooterResult = await n.fromUnsafe(
+      () => fs.writeFile(
+        path.resolve(
+          path.dirname(parseConfigResult.filePath),
+          config.root ?? "./",
+          legacyFooter.path
+        ),
+        legacyFooter.footerString
+      ),
+      (originalError) => createError("FAILED_TO_WRITE_UPGRADED_FOOTER", originalError)
+    );
+    if (!writeUpgradedFooterResult.success) {
+      return output.error().title("Could not save upgraded footer.").message(writeUpgradedFooterResult.error.code).message(displayError(writeUpgradedFooterResult.error.detail)).exit("error");
+    }
+  }
+  if (legacyScript) {
+    const writeUpgradedScriptResult = await n.fromUnsafe(
+      () => fs.writeFile(
+        path.resolve(
+          path.dirname(parseConfigResult.filePath),
+          config.root ?? "./",
+          legacyScript.path
+        ),
+        legacyScript.scriptString
+      ),
+      (originalError) => createError("FAILED_TO_WRITE_UPGRADED_SCRIPT", originalError)
+    );
+    if (!writeUpgradedScriptResult.success) {
+      return output.error().title("Could not save upgraded head script.").message(writeUpgradedScriptResult.error.code).message(displayError(writeUpgradedScriptResult.error.detail)).exit("error");
+    }
+  }
+  const writeUpgradedConfigResult = await n.fromUnsafe(
+    () => fs.writeFile(
+      parseConfigResult.filePath,
+      JSON.stringify(upgradedConfig, null, 2)
+    ),
+    (originalError) => createError("FAILED_TO_WRITE_UPGRADED_CONFIG", originalError)
+  );
+  if (!writeUpgradedConfigResult.success) {
+    return output.error().title("Could not save upgraded config.").message(writeUpgradedConfigResult.error.code).message(displayError(writeUpgradedConfigResult.error.detail)).exit("error");
+  }
+  return output.info().title("Successfully upgraded Scalar Docs configuration!").message("Run `scalar project preview` to preview your project").exit("success");
+}
+export {
+  upgradeAction
+};

package/chunks/action-4XI7XJR4.js

@@ -0,0 +1,204 @@
+import { createRequire as $$cR } from "node:module"; const require = $$cR(import.meta.url);
+import {
+  openBrowser
+} from "./chunk-JFIXNSPP.js";
+import {
+  accessTokenPayloadSchema,
+  decode,
+  generateAccessByPersonalToken,
+  setAuthData,
+  tokenResponseSchema
+} from "./chunk-M37TP6U2.js";
+import {
+  config
+} from "./chunk-4ZDQXWBT.js";
+import "./chunk-VNYE4R7N.js";
+import "./chunk-OQKDBLOZ.js";
+import "./chunk-4ORL4MST.js";
+import {
+  output
+} from "./chunk-T5HJUAWB.js";
+import {
+  external_exports
+} from "./chunk-IKT5F47M.js";
+import "./chunk-3MZYUBJ6.js";
+
+// src/domains/auth/login/action.ts
+import as2 from "ansis";
+
+// ../../packages/mongobase-client/dist/auth/node/exchange-callback-server.js
+import getPort from "get-port";
+var generateTokenCallbackEndpoint = async (exchangeUrl) => {
+  const http = await import("node:http");
+  const port = await getPort();
+  const server = http.createServer();
+  server.listen({ port, host: "127.0.0.1" });
+  const getTokens = async () => {
+    const resultPromise = new Promise((resolve) => {
+      server.on("request", async (req, res) => {
+        const corsOrigin = `http://127.0.0.1:${port}`;
+        const errorResponse = (message, code) => {
+          res.writeHead(code, {
+            "Content-Type": "application/json",
+            "Access-Control-Allow-Origin": corsOrigin
+          });
+          res.end(JSON.stringify({
+            success: false,
+            error: true,
+            message
+          }));
+          server.close();
+          return resolve({ data: null, error: true });
+        };
+        if (req.method !== "POST") {
+          return errorResponse("Method not allowed", 405);
+        }
+        const url = new URL(`http://localhost:${port}${req.url}`);
+        const exchangeToken = url.searchParams.get("exchangeToken");
+        if (!exchangeToken) {
+          return errorResponse("Missing exchange token", 400);
+        }
+        try {
+          const tokens = await exchangeTokenForAccess(exchangeUrl, exchangeToken);
+          if (tokens) {
+            res.writeHead(200, {
+              "Content-Type": "application/json",
+              "Access-Control-Allow-Origin": corsOrigin
+            });
+            res.end(JSON.stringify({
+              success: true,
+              error: false,
+              message: "Token exchanged. "
+            }));
+            server.close();
+            return resolve({ data: tokens, error: false });
+          }
+          return errorResponse("Failed to exchange token", 400);
+        } catch (err) {
+          console.error(err);
+          return errorResponse("Internal server error", 500);
+        }
+      });
+    });
+    const timeoutPromise = new Promise((resolve) => {
+      setTimeout(() => {
+        server.close();
+        resolve({ data: null, error: true });
+      }, 3 * 60 * 1e3);
+    });
+    return Promise.race([resultPromise, timeoutPromise]);
+  };
+  return {
+    port,
+    cancel: () => server.close(),
+    getTokens
+  };
+};
+var exchangeTokenForAccess = async (serverUrl, exchangeToken) => {
+  const result = await fetch(serverUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({
+      exchangeToken
+    })
+  });
+  if (result.ok) {
+    return tokenResponseSchema.parse(await result.json());
+  }
+  return null;
+};
+
+// src/domains/auth/login/helpers/messages.ts
+import as from "ansis";
+function loggedInMessage(userIdentifier) {
+  if (process.env.CI || !userIdentifier)
+    return "Successfully authenticated to Scalar CLI";
+  return `Successfully authenticated to Scalar CLI as ${as.cyan(userIdentifier)}`;
+}
+
+// src/domains/auth/login/helpers/email-pass-auth.ts
+var tokenResponseSchema2 = external_exports.object({
+  accessToken: external_exports.string(),
+  refreshToken: external_exports.string()
+});
+var emailPasswordAuth = async ({
+  email,
+  password
+}) => {
+  const result = await fetch(`${config.services.api}/core/login/email`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json"
+    },
+    credentials: "include",
+    body: JSON.stringify({
+      email,
+      password
+    })
+  });
+  if (!result.ok) {
+    const data = await result.json();
+    throw new Error(data.message ?? "Could not login with email");
+  }
+  return tokenResponseSchema2.parse(await result.json());
+};
+
+// src/domains/auth/login/action.ts
+async function loginAction({
+  email,
+  password,
+  token: _token
+}) {
+  const token = process.env.SCALAR_API_KEY || _token;
+  if (token) {
+    try {
+      const { accessToken } = await generateAccessByPersonalToken({
+        personalToken: token
+      });
+      const { email: userEmail } = decode(accessToken, accessTokenPayloadSchema);
+      output.info().message(loggedInMessage(userEmail)).print();
+    } catch (err) {
+      return output.error().title("Invalid token").message(err.message ?? "Please provide a valid personal token").exit("error");
+    }
+    return;
+  }
+  if (email || password) {
+    if (!email || !password) {
+      return output.error().title("Please provide both email and password combination").message().exit("error");
+    }
+    try {
+      const { accessToken, refreshToken } = await emailPasswordAuth({
+        email,
+        password
+      });
+      await setAuthData({ accessToken, refreshToken });
+      output.info().message(loggedInMessage(email)).print();
+    } catch (err) {
+      output.error().title(err.message).print();
+    }
+    return;
+  }
+  const { port, getTokens } = await generateTokenCallbackEndpoint(
+    `${config.services.api}/core/login/exchange`
+  );
+  const loginUrl = `${config.projects.dashboard}/login?externalRedirect=local&port=${port}`;
+  output.info().message(`Please follow the link to login: ${as2.cyan(loginUrl)}`).print();
+  openBrowser(loginUrl);
+  try {
+    const tokenResult = await getTokens();
+    if (tokenResult.error) throw Error("Unable to exchange token");
+    await setAuthData(tokenResult.data);
+    const { email: userEmail } = decode(
+      tokenResult.data.accessToken,
+      accessTokenPayloadSchema
+    );
+    return output.info().message(loggedInMessage(userEmail)).exit("success");
+  } catch {
+    return output.error().title("Something went wrong. Please try again.").exit("error");
+  }
+}
+export {
+  loginAction
+};

package/chunks/action-5IU77OII.js

@@ -0,0 +1,60 @@
+import { createRequire as $$cR } from "node:module"; const require = $$cR(import.meta.url);
+import {
+  getFileOrUrl
+} from "./chunk-24WAOKGG.js";
+import {
+  require_dist
+} from "./chunk-K74E42RV.js";
+import "./chunk-CISTON3A.js";
+import "./chunk-Q7DOQHZN.js";
+import {
+  isYamlFileName
+} from "./chunk-4ORL4MST.js";
+import {
+  output
+} from "./chunk-T5HJUAWB.js";
+import "./chunk-GSGZHE26.js";
+import "./chunk-IKT5F47M.js";
+import {
+  __toESM
+} from "./chunk-3MZYUBJ6.js";
+
+// src/domains/document/postman/action.ts
+var import_yaml = __toESM(require_dist(), 1);
+import fs from "node:fs";
+import as from "ansis";
+import { convert } from "@scalar/postman-to-openapi";
+async function convertAction(inputArgument, {
+  output: outputPath,
+  mergeOperations
+}) {
+  const startTime = performance.now();
+  if (!inputArgument) {
+    return output.error().title("Invalid argument").message("Please provide a Postman collection file path or URL").exit("error");
+  }
+  const collection = await getFileOrUrl(inputArgument);
+  let specification;
+  try {
+    specification = convert(collection, {
+      mergeOperation: !!mergeOperations
+    });
+  } catch {
+    return output.error().title("Failed to convert Postman collection").message("The provided input is not a valid Postman collection").exit("error");
+  }
+  const openApiDocument = outputPath ? isYamlFileName(outputPath) ? import_yaml.default.stringify(specification) : JSON.stringify(specification, null, 2) : JSON.stringify(specification, null, 2);
+  if (outputPath) {
+    fs.writeFileSync(outputPath, openApiDocument, "utf8");
+    const endTime = performance.now();
+    output.info().line(
+      `${as.green("OpenAPI document generated")} ${as.grey(
+        `in ${as.white(`${as.bold(`${Math.round(endTime - startTime)}`)} ms`)}`
+      )}`
+    ).line(`Written to ${as.cyan(outputPath)}`).print();
+    return;
+  }
+  process.stdout.write(`${openApiDocument}
+`);
+}
+export {
+  convertAction
+};

package/chunks/action-B3KKREWQ.js

@@ -0,0 +1,64 @@
+import { createRequire as $$cR } from "node:module"; const require = $$cR(import.meta.url);
+import {
+  isAsyncApiDocument
+} from "./chunk-24WAOKGG.js";
+import "./chunk-CISTON3A.js";
+import "./chunk-Q7DOQHZN.js";
+import "./chunk-4ORL4MST.js";
+import {
+  output
+} from "./chunk-T5HJUAWB.js";
+import "./chunk-GSGZHE26.js";
+import "./chunk-IKT5F47M.js";
+import "./chunk-3MZYUBJ6.js";
+
+// src/domains/document/validate/action.ts
+import as from "ansis";
+import prettyjson from "prettyjson";
+import { validate as validateAsyncApi } from "@scalar/asyncapi-validator";
+import { bundle } from "@scalar/json-magic/bundle";
+import { fetchUrls, readFiles } from "@scalar/json-magic/bundle/plugins/node";
+import { validate as validateOpenApi } from "@scalar/openapi-validator";
+async function validateAction(inputArgument) {
+  const startTime = performance.now();
+  if (!inputArgument) {
+    return output.error().title("Invalid argument").message("Please provide a file path").exit("error");
+  }
+  const document = await bundle(inputArgument, {
+    plugins: [readFiles(), fetchUrls()],
+    treeShake: false,
+    depth: -1
+  });
+  const isAsyncApi = isAsyncApiDocument(document);
+  const specification = isAsyncApi ? "AsyncAPI" : "OpenAPI";
+  const result = isAsyncApi ? validateAsyncApi(document) : validateOpenApi(document);
+  if (result.valid && result.version) {
+    const endTime = performance.now();
+    output.info().line(
+      as.green(
+        `Matches the ${specification} specification${as.white(` (${specification} ${as.bold(result.version)})`)}
+`
+      )
+    ).line(
+      `${as.green("File validated")} ${as.grey(
+        `in ${as.white(`${as.bold(`${Math.round(endTime - startTime)}`)} ms`)}
+`
+      )}`
+    ).print();
+  } else {
+    output.error().message(prettyjson.render(result.errors)).message(
+      as.red(
+        `File does not match the ${specification} ${result.version ? `${result.version} ` : ""}specification.`
+      )
+    ).message(
+      as.red(
+        `${as.bold(
+          `${result.errors?.length} error${result.errors && result.errors.length > 1 ? "s" : ""}`
+        )} found.`
+      )
+    ).exit("error");
+  }
+}
+export {
+  validateAction
+};