@fern-api/fern-api-dev 3.27.3 → 3.29.0

package/cli.cjs

@@ -1413817,7 +1413817,7 @@ var AccessTokenPosthogManager = class {
         properties: {
           ...event,
           ...event.properties,
-          version: "3.27.3",
+          version: "3.29.0",
           usingAccessToken: true
         }
       });
@@ -1413916,7 +1413916,7 @@ var UserPosthogManager = class {
       distinctId: this.userId ?? await this.getPersistedDistinctId(),
       event: "CLI",
       properties: {
-        version: "3.27.3",
+        version: "3.29.0",
         ...event,
         ...event.properties,
         usingAccessToken: false,
@@ -1493982,7 +1493982,7 @@ var CliContext = class {
     if (false) {
       this.logger.error("CLI_VERSION is not defined");
     }
-    return "3.27.3";
+    return "3.29.0";
   }
   getCliName() {
     if (false) {
@@ -1588481,7 +1588481,7 @@ var import_path35 = __toESM(require("path"), 1);
 var LOCAL_STORAGE_FOLDER4 = ".fern-dev";
 var LOGS_FOLDER_NAME = "logs";
 function getCliSource() {
-  const version6 = "3.27.3";
+  const version6 = "3.29.0";
   return `cli@${version6}`;
 }
 var DebugLogger = class {
@@ -1604996,7 +1604996,8 @@ function logViolationsGroup({
     if (title5 === "") {
       title5 = violation.relativeFilepath;
     }
-    return violation.message;
+    const severityLabel = getSeverityLabel(violation.severity);
+    return `${severityLabel} ${violation.message}`;
   }).filter((message) => message != null).join("\n");
   context2.logger.log(
     getLogLevelForSeverity(severity),
@@ -1605032,6 +1605033,18 @@ function getLogLevelForSeverity(severity) {
       assertNever(severity);
   }
 }
+function getSeverityLabel(severity) {
+  switch (severity) {
+    case "fatal":
+      return source_default.red("[error]");
+    case "error":
+      return source_default.red("[error]");
+    case "warning":
+      return source_default.yellow("[warning]");
+    default:
+      assertNever(severity);
+  }
+}
 function logViolationsSummary({
   stats,
   context: context2,
@@ -1605079,6 +1605092,39 @@ function getViolationStats(violations) {
 }
 
 // src/commands/validate/validateDocsWorkspaceAndLogIssues.ts
+async function collectDocsWorkspaceViolations({
+  workspace,
+  apiWorkspaces,
+  ossWorkspaces,
+  context: context2,
+  errorOnBrokenLinks,
+  excludeRules
+}) {
+  if (workspace.config.settings?.substituteEnvVars) {
+    workspace.config = replaceEnvVariables(workspace.config, {
+      onError: (e6) => context2.failAndThrow(e6)
+    });
+  }
+  const startTime = performance.now();
+  const violations = await validateDocsWorkspace(
+    workspace,
+    context2,
+    apiWorkspaces,
+    ossWorkspaces,
+    false,
+    excludeRules
+  );
+  const elapsedMillis = performance.now() - startTime;
+  let hasErrors = violations.some((v21) => v21.severity === "fatal" || v21.severity === "error");
+  if (errorOnBrokenLinks) {
+    hasErrors = hasErrors || violations.some((violation) => violation.name === "valid-markdown-links");
+  }
+  return {
+    violations,
+    elapsedMillis,
+    hasErrors
+  };
+}
 async function validateDocsWorkspaceWithoutExiting({
   workspace,
   apiWorkspaces,
@@ -1605251,6 +1605297,110 @@ async function previewDocsWorkspace({
   return;
 }
 
+// src/commands/docs-preview/deleteDocsPreview.ts
+var PREVIEW_URL_PATTERN = /^[a-z0-9-]+-preview-[a-z0-9]+\.docs\.buildwithfern\.com$/i;
+function isPreviewUrl(url2) {
+  let hostname = url2.toLowerCase().trim();
+  if (hostname.startsWith("https://")) {
+    hostname = hostname.slice(8);
+  } else if (hostname.startsWith("http://")) {
+    hostname = hostname.slice(7);
+  }
+  const slashIndex = hostname.indexOf("/");
+  if (slashIndex !== -1) {
+    hostname = hostname.slice(0, slashIndex);
+  }
+  return PREVIEW_URL_PATTERN.test(hostname);
+}
+async function deleteDocsPreview({
+  cliContext,
+  previewUrl
+}) {
+  if (!isPreviewUrl(previewUrl)) {
+    cliContext.failAndThrow(
+      `Invalid preview URL: ${previewUrl}
+Only preview sites can be deleted with this command.
+Preview URLs follow the pattern: {org}-preview-{hash}.docs.buildwithfern.com
+Example: acme-preview-abc123.docs.buildwithfern.com`
+    );
+    return;
+  }
+  const token = await cliContext.runTask(async (context2) => {
+    return askToLogin(context2);
+  });
+  if (token == null) {
+    cliContext.failAndThrow("Failed to authenticate. Please run 'fern login' first.");
+    return;
+  }
+  await cliContext.runTask(async (context2) => {
+    context2.logger.info(`Deleting preview site: ${previewUrl}`);
+    const fdr = createFdrService({ token: token.value });
+    const deleteResponse = await fdr.docs.v2.write.deleteDocsSite({
+      url: previewUrl
+    });
+    if (deleteResponse.ok) {
+      context2.logger.info(source_default.green(`Successfully deleted preview site: ${previewUrl}`));
+    } else {
+      switch (deleteResponse.error.error) {
+        case "UnauthorizedError":
+          return context2.failAndThrow(
+            "You do not have permissions to delete this preview site. Reach out to support@buildwithfern.com"
+          );
+        case "DocsNotFoundError":
+          return context2.failAndThrow(`Preview site not found: ${previewUrl}`);
+        default:
+          return context2.failAndThrow(`Failed to delete preview site: ${previewUrl}`, deleteResponse.error);
+      }
+    }
+  });
+}
+
+// src/commands/docs-preview/listDocsPreview.ts
+async function listDocsPreview({
+  cliContext,
+  limit,
+  page
+}) {
+  const token = await cliContext.runTask(async (context2) => {
+    return askToLogin(context2);
+  });
+  if (token == null) {
+    cliContext.failAndThrow("Failed to authenticate. Please run 'fern login' first.");
+    return;
+  }
+  await cliContext.runTask(async (context2) => {
+    context2.logger.info("Fetching preview deployments...");
+    const fdr = createFdrService({ token: token.value });
+    const listResponse = await fdr.docs.v2.read.listAllDocsUrls({
+      page,
+      limit: limit ?? 100
+    });
+    if (!listResponse.ok) {
+      return context2.failAndThrow("Failed to fetch docs URLs", listResponse.error);
+    }
+    const previewUrlPattern = /-preview-[a-f0-9]+\.docs\.buildwithfern\.com$/;
+    const previewDeployments = listResponse.body.urls.filter((item) => previewUrlPattern.test(item.domain)).map((item) => ({
+      url: item.basePath != null ? `${item.domain}${item.basePath}` : item.domain,
+      organizationId: item.organizationId,
+      updatedAt: item.updatedAt
+    }));
+    if (previewDeployments.length === 0) {
+      context2.logger.info("No preview deployments found.");
+      return;
+    }
+    context2.logger.info(source_default.bold(`
+Found ${previewDeployments.length} preview deployment(s):
+`));
+    for (const deployment of previewDeployments) {
+      const updatedDate = new Date(deployment.updatedAt).toLocaleString();
+      context2.logger.info(`  ${source_default.cyan(deployment.url)}`);
+      context2.logger.info(`    Organization: ${deployment.organizationId}`);
+      context2.logger.info(`    Updated: ${updatedDate}
+`);
+    }
+  });
+}
+
 // src/commands/downgrade/downgrade.ts
 var import_promises80 = require("fs/promises");
 
@@ -1638023,6 +1638173,30 @@ async function runRulesOnOSSWorkspace({ workspace, context: context2, rules }) {
 
 // src/commands/validate/validateAPIWorkspaceAndLogIssues.ts
 var import_validate_npm_package_name = __toESM(require_lib20(), 1);
+async function collectAPIWorkspaceViolations({
+  workspace,
+  context: context2,
+  ossWorkspace
+}) {
+  if (!(0, import_validate_npm_package_name.default)(workspace.definition.rootApiFile.contents.name).validForNewPackages) {
+    context2.failAndThrow("API name is not valid.");
+  }
+  const startTime = performance.now();
+  const apiViolations = validateFernWorkspace(workspace, context2.logger);
+  const generatorViolations = await validateGeneratorsWorkspace(workspace, context2.logger);
+  const violations = [...apiViolations, ...generatorViolations];
+  if (ossWorkspace) {
+    violations.push(...await validateOSSWorkspace(ossWorkspace, context2));
+  }
+  const elapsedMillis = performance.now() - startTime;
+  const hasErrors = violations.some((v21) => v21.severity === "fatal" || v21.severity === "error");
+  return {
+    apiName: workspace.definition.rootApiFile.contents.name,
+    violations,
+    elapsedMillis,
+    hasErrors
+  };
+}
 async function validateAPIWorkspaceWithoutExiting({
   workspace,
   context: context2,
@@ -1643812,6 +1643986,230 @@ async function validateDocsBrokenLinks({
   });
 }
 
+// src/commands/validate/printCheckReport.ts
+function printCheckReport({ apiResults, docsResult, logWarnings, context: context2 }) {
+  const startTime = performance.now();
+  let hasErrors = false;
+  const apiResultsWithViolations = apiResults.filter((result) => {
+    const stats = getViolationStats2(result.violations);
+    return stats.numErrors > 0 || logWarnings && stats.numWarnings > 0;
+  });
+  if (apiResultsWithViolations.length > 0) {
+    const totalSdkStats = getTotalStats(apiResults.map((r23) => r23.violations).flat());
+    const showApiNesting = apiResults.length > 1;
+    if (showApiNesting) {
+      context2.logger.info(source_default.cyan(source_default.bold("[sdk]")));
+      for (const apiResult of apiResults) {
+        const stats = getViolationStats2(apiResult.violations);
+        if (stats.numErrors > 0 || logWarnings && stats.numWarnings > 0) {
+          hasErrors = hasErrors || stats.numErrors > 0;
+          printApiSection({
+            apiName: apiResult.apiName,
+            violations: apiResult.violations,
+            stats,
+            logWarnings,
+            context: context2,
+            indent: "    "
+          });
+        }
+      }
+    } else {
+      hasErrors = hasErrors || totalSdkStats.numErrors > 0;
+      printSdkSectionFlat({
+        violations: apiResults[0]?.violations ?? [],
+        stats: totalSdkStats,
+        logWarnings,
+        context: context2
+      });
+    }
+  }
+  if (docsResult != null) {
+    const docsStats = getViolationStats2(docsResult.violations);
+    if (docsStats.numErrors > 0 || logWarnings && docsStats.numWarnings > 0) {
+      hasErrors = hasErrors || docsStats.numErrors > 0;
+      printDocsSection({
+        violations: docsResult.violations,
+        stats: docsStats,
+        logWarnings,
+        context: context2
+      });
+    }
+  }
+  const totalElapsedMillis = performance.now() - startTime;
+  const allViolations = [...apiResults.map((r23) => r23.violations).flat(), ...docsResult?.violations ?? []];
+  const totalStats = getViolationStats2(allViolations);
+  printSummary({
+    stats: totalStats,
+    logWarnings,
+    elapsedMillis: totalElapsedMillis,
+    context: context2
+  });
+  return { hasErrors };
+}
+function printSdkSectionFlat({
+  violations,
+  stats,
+  logWarnings,
+  context: context2
+}) {
+  const statsStr = formatStats(stats, logWarnings);
+  context2.logger.info(source_default.cyan(source_default.bold(`[sdk]`)) + ` ${statsStr}`);
+  printViolationsByType({
+    violations,
+    logWarnings,
+    context: context2,
+    indent: "    "
+  });
+}
+function printApiSection({
+  apiName,
+  violations,
+  stats,
+  logWarnings,
+  context: context2,
+  indent: indent3
+}) {
+  const statsStr = formatStats(stats, logWarnings);
+  context2.logger.info(`${indent3}${source_default.bold(`[${apiName}]`)} ${statsStr}`);
+  printViolationsByType({
+    violations,
+    logWarnings,
+    context: context2,
+    indent: indent3 + "    "
+  });
+}
+function printDocsSection({
+  violations,
+  stats,
+  logWarnings,
+  context: context2
+}) {
+  const statsStr = formatStats(stats, logWarnings);
+  context2.logger.info(source_default.magenta(source_default.bold(`[docs]`)) + ` ${statsStr}`);
+  printViolationsByType({
+    violations,
+    logWarnings,
+    context: context2,
+    indent: "    "
+  });
+}
+function printViolationsByType({
+  violations,
+  logWarnings,
+  context: context2,
+  indent: indent3
+}) {
+  const errors4 = violations.filter((v21) => v21.severity === "fatal" || v21.severity === "error");
+  const warnings = violations.filter((v21) => v21.severity === "warning");
+  if (logWarnings) {
+    for (const violation of warnings.sort(sortViolations)) {
+      printViolation({ violation, context: context2, indent: indent3 });
+    }
+  }
+  for (const violation of errors4.sort(sortViolations)) {
+    printViolation({ violation, context: context2, indent: indent3 });
+  }
+}
+function printViolation({
+  violation,
+  context: context2,
+  indent: indent3
+}) {
+  const severityLabel = getSeverityLabel2(violation.severity);
+  const path68 = formatViolationPath(violation);
+  if (path68 === "") {
+    context2.logger.info(`${indent3}${severityLabel} ${violation.message}`);
+  } else {
+    context2.logger.info(`${indent3}${severityLabel}`);
+    context2.logger.info(`${indent3}    path: ${source_default.blue(path68)}`);
+    context2.logger.info(`${indent3}    issue: ${violation.message}`);
+  }
+  context2.logger.info("");
+}
+function formatViolationPath(violation) {
+  const parts = [];
+  if (violation.relativeFilepath !== "") {
+    parts.push(violation.relativeFilepath);
+  }
+  for (const nodePathItem of violation.nodePath) {
+    let itemStr = typeof nodePathItem === "string" ? nodePathItem : nodePathItem.key;
+    if (typeof nodePathItem !== "string" && nodePathItem.arrayIndex != null) {
+      itemStr += `[${nodePathItem.arrayIndex}]`;
+    }
+    parts.push(itemStr);
+  }
+  return parts.join(" -> ");
+}
+function getSeverityLabel2(severity) {
+  switch (severity) {
+    case "fatal":
+      return source_default.red("[error]");
+    case "error":
+      return source_default.red("[error]");
+    case "warning":
+      return source_default.yellow("[warning]");
+    default:
+      assertNever(severity);
+  }
+}
+function formatStats(stats, logWarnings) {
+  const parts = [];
+  if (stats.numErrors > 0) {
+    parts.push(`${stats.numErrors} error${stats.numErrors !== 1 ? "s" : ""}`);
+  }
+  if (logWarnings && stats.numWarnings > 0) {
+    parts.push(`${stats.numWarnings} warning${stats.numWarnings !== 1 ? "s" : ""}`);
+  }
+  return parts.join(", ");
+}
+function getViolationStats2(violations) {
+  let numErrors = 0;
+  let numWarnings = 0;
+  for (const violation of violations) {
+    switch (violation.severity) {
+      case "fatal":
+      case "error":
+        numErrors += 1;
+        break;
+      case "warning":
+        numWarnings += 1;
+        break;
+      default:
+        assertNever(violation.severity);
+    }
+  }
+  return { numErrors, numWarnings };
+}
+function getTotalStats(violations) {
+  return getViolationStats2(violations);
+}
+function sortViolations(a10, b18) {
+  const pathCompare = a10.relativeFilepath.localeCompare(b18.relativeFilepath);
+  if (pathCompare !== 0) {
+    return pathCompare;
+  }
+  return JSON.stringify(a10.nodePath).localeCompare(JSON.stringify(b18.nodePath));
+}
+function printSummary({
+  stats,
+  logWarnings,
+  elapsedMillis,
+  context: context2
+}) {
+  const suffix = elapsedMillis > 0 ? ` in ${(elapsedMillis / 1e3).toFixed(3)} seconds.` : ".";
+  let message = `Found ${stats.numErrors} error${stats.numErrors !== 1 ? "s" : ""} and ${stats.numWarnings} warning${stats.numWarnings !== 1 ? "s" : ""}` + suffix;
+  if (!logWarnings && stats.numWarnings > 0) {
+    message += " Run fern check --warnings to print out the warnings not shown.";
+  }
+  if (stats.numErrors > 0) {
+    context2.logger.error(message);
+  } else if (stats.numWarnings > 0) {
+    context2.logger.warn(message);
+  } else {
+    context2.logger.info(source_default.green("All checks passed"));
+  }
+}
+
 // src/commands/validate/validateWorkspaces.ts
 async function validateWorkspaces({
   project,
@@ -1643822,28 +1644220,41 @@ async function validateWorkspaces({
   isLocal,
   directFromOpenapi
 }) {
+  const apiResults = [];
+  let docsResult;
+  let hasAnyErrors = false;
   const docsWorkspace = project.docsWorkspaces;
   if (docsWorkspace != null) {
+    const excludeRules = brokenLinks || errorOnBrokenLinks ? [] : ["valid-markdown-links"];
+    const ossWorkspaces = await filterOssWorkspaces(project);
+    let collected;
     await cliContext.runTaskForWorkspace(docsWorkspace, async (context2) => {
-      const excludeRules = brokenLinks || errorOnBrokenLinks ? [] : ["valid-markdown-links"];
-      await validateDocsWorkspaceAndLogIssues({
+      collected = await collectDocsWorkspaceViolations({
         workspace: docsWorkspace,
         context: context2,
-        logWarnings,
         apiWorkspaces: project.apiWorkspaces,
-        ossWorkspaces: await filterOssWorkspaces(project),
+        ossWorkspaces,
         errorOnBrokenLinks,
         excludeRules
       });
     });
+    if (collected != null) {
+      docsResult = {
+        violations: collected.violations,
+        elapsedMillis: collected.elapsedMillis
+      };
+      if (collected.hasErrors) {
+        hasAnyErrors = true;
+      }
+    }
   }
   await Promise.all(
     project.apiWorkspaces.map(async (workspace) => {
-      if (workspace.generatorsConfiguration?.groups.length === 0 && workspace.type != "fern") {
+      if (workspace.generatorsConfiguration?.groups.length === 0 && workspace.type !== "fern") {
         return;
       }
-      await cliContext.runTaskForWorkspace(workspace, async (context2) => {
-        if (workspace instanceof OSSWorkspace && directFromOpenapi) {
+      if (workspace instanceof OSSWorkspace && directFromOpenapi) {
+        await cliContext.runTaskForWorkspace(workspace, async (context2) => {
           await workspace.getIntermediateRepresentation({
             context: context2,
             audiences: { type: "all" },
@@ -1643851,18 +1644262,56 @@ async function validateWorkspaces({
             generateV1Examples: false,
             logWarnings
           });
+        });
+        return;
+      }
+      if (workspace instanceof LazyFernWorkspace) {
+        const absolutePathToApiYml = join2(
+          workspace.absoluteFilePath,
+          RelativeFilePath2.of(DEFINITION_DIRECTORY),
+          RelativeFilePath2.of(ROOT_API_FILENAME)
+        );
+        const apiYmlExists = await doesPathExist(absolutePathToApiYml);
+        if (!apiYmlExists) {
+          await cliContext.runTask(async (context2) => {
+            context2.logger.error(`Missing file: ${ROOT_API_FILENAME}`);
+            return context2.failAndThrow();
+          });
           return;
         }
+      }
+      let collected;
+      await cliContext.runTaskForWorkspace(workspace, async (context2) => {
         const fernWorkspace = await workspace.toFernWorkspace({ context: context2 });
-        await validateAPIWorkspaceAndLogIssues({
+        collected = await collectAPIWorkspaceViolations({
           workspace: fernWorkspace,
           context: context2,
-          logWarnings,
           ossWorkspace: workspace instanceof OSSWorkspace ? workspace : void 0
         });
       });
+      if (collected != null) {
+        apiResults.push({
+          apiName: collected.apiName,
+          violations: collected.violations,
+          elapsedMillis: collected.elapsedMillis
+        });
+        if (collected.hasErrors) {
+          hasAnyErrors = true;
+        }
+      }
     })
   );
+  const { hasErrors } = await cliContext.runTask((context2) => {
+    return printCheckReport({
+      apiResults,
+      docsResult,
+      logWarnings,
+      context: context2
+    });
+  });
+  if (hasErrors || hasAnyErrors) {
+    cliContext.failAndThrow();
+  }
 }
 
 // src/commands/write-definition/writeDefinitionForWorkspaces.ts
@@ -1646365,12 +1646814,63 @@ function addWriteDefinitionCommand(cli, cliContext) {
 }
 function addDocsCommand(cli, cliContext) {
   cli.command("docs", "Commands for managing your docs", (yargs) => {
-    addDocsPreviewCommand(yargs, cliContext);
+    addDocsDevCommand(yargs, cliContext);
     addDocsBrokenLinksCommand(yargs, cliContext);
+    addDocsPreviewCommand(yargs, cliContext);
     return yargs;
   });
 }
 function addDocsPreviewCommand(cli, cliContext) {
+  cli.command("preview", "Commands for managing preview deployments", (yargs) => {
+    addDocsPreviewListCommand(yargs, cliContext);
+    addDocsPreviewDeleteCommand(yargs, cliContext);
+    return yargs;
+  });
+}
+function addDocsPreviewListCommand(cli, cliContext) {
+  cli.command(
+    "list",
+    "List all preview deployments",
+    (yargs) => yargs.option("limit", {
+      type: "number",
+      description: "Maximum number of preview deployments to display"
+    }).option("page", {
+      type: "number",
+      description: "Page number for pagination (starts at 1)"
+    }),
+    async (argv) => {
+      await cliContext.instrumentPostHogEvent({
+        command: "fern docs preview list"
+      });
+      await listDocsPreview({
+        cliContext,
+        limit: argv.limit,
+        page: argv.page
+      });
+    }
+  );
+}
+function addDocsPreviewDeleteCommand(cli, cliContext) {
+  cli.command(
+    "delete <url>",
+    "Delete a preview deployment",
+    (yargs) => yargs.positional("url", {
+      type: "string",
+      description: "The FQDN of the preview deployment to delete (e.g. acme-preview-abc123.docs.buildwithfern.com)",
+      demandOption: true
+    }),
+    async (argv) => {
+      await cliContext.instrumentPostHogEvent({
+        command: "fern docs preview delete"
+      });
+      await deleteDocsPreview({
+        cliContext,
+        previewUrl: argv.url
+      });
+    }
+  );
+}
+function addDocsDevCommand(cli, cliContext) {
   cli.command(
     "dev",
     "Run a local development server to preview your docs",

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.27.3",
+  "version": "3.29.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fern-api/fern.git",