@mintlify/cli 4.0.1197 → 4.0.1199

package/bin/welcome.js

@@ -0,0 +1,107 @@
+import chalk from 'chalk';
+import { MINT_GREEN, MINT_LOGO, MINT_LOGO_WIDTH } from './logo.js';
+const mint = chalk.hex(MINT_GREEN);
+const TAGLINE = 'Build, preview, and ship beautiful docs.';
+// Row at which the identity block starts beside the logo, and the gap between
+// the logo's right edge and that block.
+const META_TOP_ROW = 6;
+const META_GAP = 4;
+const GROUPS = [
+    {
+        title: 'Preview',
+        commands: [
+            { name: 'dev', description: 'Start a local preview of your docs' },
+            { name: 'new', description: 'Scaffold a new documentation site' },
+        ],
+    },
+    {
+        title: 'Quality',
+        commands: [
+            { name: 'validate', description: 'Validate the docs build (strict)' },
+            { name: 'broken-links', description: 'Find broken links before you ship' },
+            { name: 'a11y', description: 'Check docs for accessibility issues' },
+            { name: 'score', description: 'Run agent-readiness checks' },
+        ],
+    },
+    {
+        title: 'Insights',
+        commands: [
+            { name: 'analytics', description: 'View analytics for your docs' },
+            { name: 'workflow', description: 'Create and manage workflows' },
+        ],
+    },
+    {
+        title: 'Account',
+        commands: [
+            { name: 'login', description: 'Authenticate with Mintlify' },
+            { name: 'logout', description: 'Sign out on this device' },
+            { name: 'status', description: 'View authentication status' },
+        ],
+    },
+    {
+        title: 'CLI',
+        commands: [
+            { name: 'config', description: 'Manage CLI configuration' },
+            { name: 'update', description: 'Update to the latest version' },
+        ],
+    },
+];
+const EXAMPLES = [
+    { name: 'dev', description: 'Start a local preview of your docs' },
+    { name: 'new docs', description: 'Scaffold a new docs site in ./docs' },
+    { name: 'validate', description: 'Validate your docs before shipping' },
+    { name: 'broken-links', description: 'Find broken links across your docs' },
+];
+const COMMAND_NAME_WIDTH = GROUPS.flatMap((group) => group.commands).reduce((max, command) => Math.max(max, command.name.length), 0) + 2;
+// `name  description`, name padded to a shared column and colored mint. Padding
+// is computed on the raw name so ANSI codes don't throw off the alignment.
+const commandRow = (name, description, nameWidth, indent) => ' '.repeat(indent) + mint(name.padEnd(nameWidth)) + chalk.dim(description);
+/**
+ * Builds the branded welcome / help screen as a ready-to-print string: the
+ * Mintlify leaf beside an identity block, then grouped examples and commands.
+ */
+export function renderWelcome({ packageName, version, signedIn, subdomain, }) {
+    const title = `${packageName.charAt(0).toUpperCase()}${packageName.slice(1)} CLI`;
+    // Only prefix "v" for real semver versions; the linked-dev build reports a
+    // descriptive string ("linked to local package").
+    const versionLabel = version ? (/^\d/.test(version) ? `v${version}` : version) : undefined;
+    const identity = [
+        chalk.bold(title) + (versionLabel ? chalk.dim(` ${versionLabel}`) : ''),
+        '',
+        chalk.dim(TAGLINE),
+        signedIn
+            ? chalk.dim('Signed in to Mintlify')
+            : chalk.dim('Run ') + mint(`${packageName} login`) + chalk.dim(' to sign in'),
+        ...(subdomain ? [chalk.dim(`Project ${subdomain}`)] : []),
+    ];
+    const lines = [''];
+    // Hero: logo on the left, identity block on the right.
+    MINT_LOGO.forEach((logoLine, index) => {
+        const identityLine = identity[index - META_TOP_ROW];
+        let row = ' ' + mint(logoLine);
+        if (identityLine) {
+            row += ' '.repeat(MINT_LOGO_WIDTH - logoLine.length + META_GAP) + identityLine;
+        }
+        lines.push(row);
+    });
+    // Examples.
+    const exampleWidth = EXAMPLES.reduce((max, example) => Math.max(max, `${packageName} ${example.name}`.length), 0) +
+        2;
+    lines.push('', ' ' + chalk.bold('EXAMPLES'));
+    for (const example of EXAMPLES) {
+        lines.push(commandRow(`${packageName} ${example.name}`, example.description, exampleWidth, 3));
+    }
+    // Commands, grouped.
+    lines.push('', ' ' + chalk.bold('COMMANDS'));
+    for (const group of GROUPS) {
+        lines.push('', '   ' + chalk.bold(group.title));
+        for (const command of group.commands) {
+            lines.push(commandRow(command.name, command.description, COMMAND_NAME_WIDTH, 5));
+        }
+    }
+    lines.push('', ' ' +
+        chalk.dim('Run ') +
+        mint(`${packageName} <command> --help`) +
+        chalk.dim(' for details on any command.'), '');
+    return lines.join('\n') + '\n';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.1197",
+  "version": "4.0.1199",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -45,12 +45,12 @@
   },
   "dependencies": {
     "@inquirer/prompts": "7.9.0",
-    "@mintlify/common": "1.0.923",
-    "@mintlify/link-rot": "3.0.1104",
+    "@mintlify/common": "1.0.924",
+    "@mintlify/link-rot": "3.0.1105",
     "@mintlify/models": "0.0.317",
-    "@mintlify/prebuild": "1.0.1068",
-    "@mintlify/previewing": "4.0.1129",
-    "@mintlify/validation": "0.1.721",
+    "@mintlify/prebuild": "1.0.1069",
+    "@mintlify/previewing": "4.0.1130",
+    "@mintlify/validation": "0.1.722",
     "adm-zip": "0.5.16",
     "chalk": "5.2.0",
     "color": "4.2.3",
@@ -90,9 +90,10 @@
     "oxlint": "1.66.0",
     "oxlint-tsgolint": "^0.23.0",
     "rimraf": "5.0.1",
+    "sharp": "^0.33.1",
     "typescript": "5.5.3",
     "vitest": "2.1.9",
     "vitest-mock-process": "1.0.4"
   },
-  "gitHead": "1e825e6876d8e7ab9d8924383a3f751670189dae"
+  "gitHead": "206c7ed073d1f20e312bdb8ff57cea11c73be0af"
 }

package/scripts/generate-logo.mjs

@@ -0,0 +1,79 @@
+// Regenerates `src/logo.ts` — the ASCII Mintlify leaf shown on the welcome
+// screen.
+//
+// Pipeline: flatten the icon's three vector paths into one solid-white
+// silhouette (so brightness-based renderers don't drop the darker leaf
+// segments), rasterize it with `sharp`, let `chafa` do the image -> ASCII shape
+// detection, then normalize every glyph to a solid `#` for the clean
+// single-color mark.
+//
+// Usage:  node scripts/generate-logo.mjs
+// Requires `sharp` (a monorepo dependency) and the `chafa` CLI on PATH.
+
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import sharp from 'sharp';
+
+const MINT_GREEN = '#18E299';
+const MINT_GREEN_DEEP = '#0C8C5E';
+
+// Paths from mintlify-icon.svg (viewBox 0 0 19 19), all filled solid white over
+// a black background so chafa sees one uniform-brightness silhouette.
+const PATHS = [
+  'M18.367 7.28888V1.59755C18.367 0.986819 17.8715 0.5 17.2699 0.5H11.5812C10.6877 0.5 9.80295 0.677018 8.98017 1.01336C8.15738 1.35856 7.40539 1.85424 6.77724 2.49152L6.733 2.53578C5.90137 3.37664 5.30862 4.42108 5.00781 5.57174C5.54749 5.43012 6.10483 5.35931 6.6622 5.35046C8.14852 5.33276 9.60831 5.81073 10.7938 6.7047C11.8643 7.50131 12.6783 8.59885 13.1206 9.86458C13.5807 11.148 13.6337 12.5465 13.2887 13.8653C14.43 13.5644 15.4828 12.9714 16.3233 12.1393L16.3675 12.0951C16.9957 11.4667 17.4999 10.7143 17.845 9.89114C18.19 9.06797 18.3581 8.18285 18.3581 7.28888H18.367Z',
+  'M4.83793 7.193C4.84674 5.44706 5.54303 3.77167 6.76814 2.51953L2.03511 7.25472C2.01749 7.27236 1.99985 7.28117 1.98222 7.29881C0.827615 8.44513 0.131342 9.97945 0.0167623 11.6019C-0.0890033 13.1186 0.307609 14.6176 1.15373 15.8698C1.23444 15.9892 1.45343 16.0285 1.57682 15.9139L4.47656 13.0216C5.38438 12.1134 5.66643 10.7642 5.23455 9.55618C4.96132 8.80666 4.82912 8.00424 4.83793 7.193Z',
+  'M16.341 12.0938C15.4332 12.9844 14.2962 13.6016 13.0623 13.875C11.8195 14.1483 10.5327 14.0689 9.33405 13.6457C9.33405 13.6457 9.32522 13.6457 9.31641 13.6457C8.10892 13.2136 6.76042 13.4958 5.8526 14.3952L2.95282 17.2875C2.82943 17.4109 2.84706 17.6137 2.99689 17.7107C4.24845 18.5484 5.74683 18.954 7.26281 18.8482C8.88455 18.7336 10.4093 18.037 11.5639 16.8818L11.608 16.8378L16.341 12.1026V12.0938Z',
+];
+
+const SIZE = '28x14'; // chafa output columns x rows
+const RES = 480; // raster resolution fed to chafa
+
+const silhouette = `<svg width="19" height="19" viewBox="0 0 19 19" xmlns="http://www.w3.org/2000/svg"><rect width="19" height="19" fill="#000"/>${PATHS.map(
+  (d) => `<path d="${d}" fill="#fff"/>`
+).join('')}</svg>`;
+
+const pngPath = join(mkdtempSync(join(tmpdir(), 'mint-logo-')), 'silhouette.png');
+await sharp(Buffer.from(silhouette)).resize(RES, RES, { fit: 'fill' }).png().toFile(pngPath);
+
+const ascii = execFileSync(
+  'chafa',
+  ['--symbols', 'ascii', '-c', 'none', '--dither', 'none', '--size', SIZE, pngPath],
+  { encoding: 'utf8' }
+);
+
+// chafa renders the shape with a brightness ramp of letters; collapse every
+// glyph to `#` for the clean single-color mark, trim trailing space, and drop
+// blank rows at the bottom.
+const art = ascii
+  .split('\n')
+  .map((line) => line.replace(/\S/g, '#').replace(/\s+$/, ''))
+  .filter(
+    (line, index, lines) => line.length > 0 || lines.slice(index).some((rest) => rest.trim())
+  );
+
+const file = `// AUTO-GENERATED by \`scripts/generate-logo.mjs\` from the Mintlify icon mark.
+// Do not edit by hand — run \`node scripts/generate-logo.mjs\` to regenerate.
+
+/** Mintlify brand greens. */
+export const MINT_GREEN = '${MINT_GREEN}';
+export const MINT_GREEN_DEEP = '${MINT_GREEN_DEEP}';
+
+/**
+ * The Mintlify leaf, rendered as a solid \`#\` mark (chafa shape detection,
+ * normalized to a single glyph). Drawn in {@link MINT_GREEN} on the welcome
+ * screen.
+ */
+export const MINT_LOGO: string[] = [
+${art.map((line) => `  '${line}',`).join('\n')}
+];
+
+/** Width of the widest logo row, for laying out content beside it. */
+export const MINT_LOGO_WIDTH = MINT_LOGO.reduce((max, line) => Math.max(max, line.length), 0);
+`;
+
+const out = join(dirname(fileURLToPath(import.meta.url)), '..', 'src', 'logo.ts');
+writeFileSync(out, file);
+console.log(`Wrote ${out} (${art.length} rows, width ${Math.max(...art.map((r) => r.length))})`);

package/src/cli.tsx

@@ -30,6 +30,7 @@ import {
   checkNodeVersion,
   autoUpgradeIfNeeded,
   getVersions,
+  isAI,
   suppressConsoleWarnings,
   terminate,
 } from './helpers.js';
@@ -44,9 +45,44 @@ import { scoreHandler } from './score/index.js';
 import { status, getCliSubdomains } from './status.js';
 import { trackTelemetryPreferenceChange } from './telemetry/track.js';
 import { update } from './update.js';
+import { renderWelcome } from './welcome.js';
 import { workflowsBuilder } from './workflows/index.js';
 
+// The branded welcome screen replaces yargs' default help, but only for an
+// interactive human at a TTY. Piped, scripted, AI, and test callers keep the
+// plain yargs help so their output stays parseable and stable.
+const shouldShowWelcome = (args: string[]): boolean => {
+  const interactive =
+    Boolean(process.stdout.isTTY) && !isAI() && process.env.CLI_TEST_MODE !== 'true';
+  if (!interactive) return false;
+  if (args.length === 0) return true;
+
+  const positionals = args.filter((arg) => !arg.startsWith('-'));
+  const command = positionals[0];
+  // `help` followed by a subcommand (e.g. `mint help dev`) is a subcommand
+  // lookup — let yargs handle it rather than intercepting with the welcome screen.
+  const isTopLevel = command === undefined || (command === 'help' && positionals.length === 1);
+  const helpRequested = command === 'help' || args.includes('--help') || args.includes('-h');
+  return isTopLevel && helpRequested;
+};
+
+const showWelcome = async (packageName: string): Promise<void> => {
+  const { cli: version } = getVersions(packageName);
+  const subdomain = getConfigValue('subdomain');
+  let signedIn = false;
+  try {
+    signedIn = Boolean(await getAccessToken());
+  } catch {}
+
+  process.stdout.write(renderWelcome({ packageName, version, signedIn, subdomain }));
+  await terminate(0);
+};
+
 export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
+  if (shouldShowWelcome(hideBin(process.argv))) {
+    return showWelcome(packageName);
+  }
+
   const telemetryMiddleware = createTelemetryMiddleware();
   render(<Logs />);
 

package/src/logo.ts

@@ -0,0 +1,31 @@
+// AUTO-GENERATED by `scripts/generate-logo.mjs` from the Mintlify icon mark.
+// Do not edit by hand — run `node scripts/generate-logo.mjs` to regenerate.
+
+/** Mintlify brand greens. */
+export const MINT_GREEN = '#18E299';
+export const MINT_GREEN_DEEP = '#0C8C5E';
+
+/**
+ * The Mintlify leaf, rendered as a solid `#` mark (chafa shape detection,
+ * normalized to a single glyph). Drawn in {@link MINT_GREEN} on the welcome
+ * screen.
+ */
+export const MINT_LOGO: string[] = [
+  '             ##############',
+  '          #################',
+  '        ###################',
+  '      #####################',
+  '    ####     ##############',
+  '  #####         ###########',
+  ' #######          #########',
+  '########           ########',
+  '########            ######',
+  '########            ####',
+  '######  ##############',
+  ' ###  ##############',
+  '    ##############',
+  '     ##########',
+];
+
+/** Width of the widest logo row, for laying out content beside it. */
+export const MINT_LOGO_WIDTH = MINT_LOGO.reduce((max, line) => Math.max(max, line.length), 0);

package/src/welcome.ts

@@ -0,0 +1,155 @@
+import chalk from 'chalk';
+
+import { MINT_GREEN, MINT_LOGO, MINT_LOGO_WIDTH } from './logo.js';
+
+const mint = chalk.hex(MINT_GREEN);
+
+const TAGLINE = 'Build, preview, and ship beautiful docs.';
+
+// Row at which the identity block starts beside the logo, and the gap between
+// the logo's right edge and that block.
+const META_TOP_ROW = 6;
+const META_GAP = 4;
+
+interface CommandEntry {
+  name: string;
+  description: string;
+}
+
+interface CommandGroup {
+  title: string;
+  commands: CommandEntry[];
+}
+
+const GROUPS: CommandGroup[] = [
+  {
+    title: 'Preview',
+    commands: [
+      { name: 'dev', description: 'Start a local preview of your docs' },
+      { name: 'new', description: 'Scaffold a new documentation site' },
+    ],
+  },
+  {
+    title: 'Quality',
+    commands: [
+      { name: 'validate', description: 'Validate the docs build (strict)' },
+      { name: 'broken-links', description: 'Find broken links before you ship' },
+      { name: 'a11y', description: 'Check docs for accessibility issues' },
+      { name: 'score', description: 'Run agent-readiness checks' },
+    ],
+  },
+  {
+    title: 'Insights',
+    commands: [
+      { name: 'analytics', description: 'View analytics for your docs' },
+      { name: 'workflow', description: 'Create and manage workflows' },
+    ],
+  },
+  {
+    title: 'Account',
+    commands: [
+      { name: 'login', description: 'Authenticate with Mintlify' },
+      { name: 'logout', description: 'Sign out on this device' },
+      { name: 'status', description: 'View authentication status' },
+    ],
+  },
+  {
+    title: 'CLI',
+    commands: [
+      { name: 'config', description: 'Manage CLI configuration' },
+      { name: 'update', description: 'Update to the latest version' },
+    ],
+  },
+];
+
+const EXAMPLES: CommandEntry[] = [
+  { name: 'dev', description: 'Start a local preview of your docs' },
+  { name: 'new docs', description: 'Scaffold a new docs site in ./docs' },
+  { name: 'validate', description: 'Validate your docs before shipping' },
+  { name: 'broken-links', description: 'Find broken links across your docs' },
+];
+
+const COMMAND_NAME_WIDTH =
+  GROUPS.flatMap((group) => group.commands).reduce(
+    (max, command) => Math.max(max, command.name.length),
+    0
+  ) + 2;
+
+// `name  description`, name padded to a shared column and colored mint. Padding
+// is computed on the raw name so ANSI codes don't throw off the alignment.
+const commandRow = (name: string, description: string, nameWidth: number, indent: number): string =>
+  ' '.repeat(indent) + mint(name.padEnd(nameWidth)) + chalk.dim(description);
+
+export interface WelcomeOptions {
+  packageName: string;
+  version?: string;
+  signedIn: boolean;
+  subdomain?: string;
+}
+
+/**
+ * Builds the branded welcome / help screen as a ready-to-print string: the
+ * Mintlify leaf beside an identity block, then grouped examples and commands.
+ */
+export function renderWelcome({
+  packageName,
+  version,
+  signedIn,
+  subdomain,
+}: WelcomeOptions): string {
+  const title = `${packageName.charAt(0).toUpperCase()}${packageName.slice(1)} CLI`;
+  // Only prefix "v" for real semver versions; the linked-dev build reports a
+  // descriptive string ("linked to local package").
+  const versionLabel = version ? (/^\d/.test(version) ? `v${version}` : version) : undefined;
+
+  const identity: string[] = [
+    chalk.bold(title) + (versionLabel ? chalk.dim(` ${versionLabel}`) : ''),
+    '',
+    chalk.dim(TAGLINE),
+    signedIn
+      ? chalk.dim('Signed in to Mintlify')
+      : chalk.dim('Run ') + mint(`${packageName} login`) + chalk.dim(' to sign in'),
+    ...(subdomain ? [chalk.dim(`Project ${subdomain}`)] : []),
+  ];
+
+  const lines: string[] = [''];
+
+  // Hero: logo on the left, identity block on the right.
+  MINT_LOGO.forEach((logoLine, index) => {
+    const identityLine = identity[index - META_TOP_ROW];
+    let row = ' ' + mint(logoLine);
+    if (identityLine) {
+      row += ' '.repeat(MINT_LOGO_WIDTH - logoLine.length + META_GAP) + identityLine;
+    }
+    lines.push(row);
+  });
+
+  // Examples.
+  const exampleWidth =
+    EXAMPLES.reduce((max, example) => Math.max(max, `${packageName} ${example.name}`.length), 0) +
+    2;
+  lines.push('', ' ' + chalk.bold('EXAMPLES'));
+  for (const example of EXAMPLES) {
+    lines.push(commandRow(`${packageName} ${example.name}`, example.description, exampleWidth, 3));
+  }
+
+  // Commands, grouped.
+  lines.push('', ' ' + chalk.bold('COMMANDS'));
+  for (const group of GROUPS) {
+    lines.push('', '   ' + chalk.bold(group.title));
+    for (const command of group.commands) {
+      lines.push(commandRow(command.name, command.description, COMMAND_NAME_WIDTH, 5));
+    }
+  }
+
+  lines.push(
+    '',
+    ' ' +
+      chalk.dim('Run ') +
+      mint(`${packageName} <command> --help`) +
+      chalk.dim(' for details on any command.'),
+    ''
+  );
+
+  return lines.join('\n') + '\n';
+}