@readme/cli 0.0.26

package/README.md

@@ -0,0 +1,55 @@
+# ReadMe CLI
+
+A command-line tool for writing, previewing, and managing your [ReadMe](https://readme.com) docs from your terminal.
+
+> **Currently in beta!** Things may change, break, or otherwise be a little rough around the edges. We'd love your feedback. Please [open an issue](https://github.com/readmeio/cli/issues) if you run into anything or have ideas for improvements.
+
+## Commands
+
+### Linting
+
+Checks your docs for errors: things like invalid frontmatter, missing files, duplicate slugs, and more. Handy for catching issues before you push.
+
+```bash
+npx @readme/cli lint [--fix] [--json]
+```
+
+Use `--fix` to automatically fix what it can, or `--json` for machine-readable output (great for CI).
+
+### OpenAPI Sync
+
+Syncs your `reference/` directory with your OpenAPI spec. It'll create, update, or remove pages based on your spec's operations.
+
+```bash
+npx @readme/cli oas:sync
+```
+
+### Import
+
+Imports content from an external folder and converts it into ReadMe's format using Claude. Great for migrating existing docs.
+
+```bash
+npx @readme/cli import
+```
+
+### Versions
+
+Lists all your doc versions and their branches.
+
+```bash
+npx @readme/cli versions
+```
+
+### Dev Server
+
+> **Very early beta!** This command is still a work in progress, and doesn't use our rendering engine yet.
+
+Starts a local dev server so you can preview your docs as you write them. Watches for changes and refreshes automatically.
+
+```bash
+npx @readme/cli dev
+```
+
+## Feedback
+
+This is a beta! If something doesn't work right, or if you have suggestions, please [open an issue](https://github.com/readmeio/cli/issues). We're actively building this and want to hear from you.

package/bin/readme.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { main } from '../src/cli.js';
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@readme/cli",
+  "version": "0.0.26",
+  "description": "The ReadMe CLI",
+  "type": "module",
+  "bin": {
+    "readme": "./bin/readme.js",
+    "readme_": "./bin/readme.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./commands/lint": "./src/commands/lint.js",
+    "./commands/oas-sync": "./src/commands/oas-sync.js",
+    "./commands/oas-validate": "./src/commands/oas-validate.js",
+    "./commands/import": "./src/commands/import.js",
+    "./commands/pretty": "./src/commands/pretty.js",
+    "./prompts": "./src/prompts/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "src",
+    "vendor",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/readme.js",
+    "test": "echo \"No tests yet\""
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "readme",
+    "cli",
+    "docs"
+  ],
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.114",
+    "@readme/markdown": "^13.3.0",
+    "@readmeio/git-format": "readmeio/git-format",
+    "ajv": "^8.18.0",
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "gray-matter": "^4.0.3",
+    "next": "^15.0.0",
+    "oas-normalize": "^15.7.1",
+    "ora": "^9.3.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "update-notifier": "^7.3.1"
+  }
+}

package/src/bootstrap.js

@@ -0,0 +1,97 @@
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import updateNotifier from 'update-notifier';
+import * as styles from './utils/styles.js';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+
+/**
+ * Run all bootstrap checks and return context about the repo.
+ * Exits with a friendly error if anything is wrong.
+ */
+export default async function bootstrap({ skipValidation = false } = {}) {
+  // 1. Check for CLI updates (runs at most once every 24 h)
+  checkForUpdates();
+
+  // 2. Find the git root (or fall back to cwd if not in a git repo)
+  const gitRoot = findGitRoot() || process.cwd();
+
+  // 3. Make sure this is a ReadMe project repo
+  if (!skipValidation) {
+    if (!findGitRoot()) {
+      styles.error('This doesn\'t appear to be a git repository.');
+      styles.info('Run this command from inside a git repo to get started.');
+      styles.info(`You can skip this check with ${styles.bold(`${styles.binName()} --no-check`)}.`);
+      process.exit(1);
+    }
+    validateReadMeRepo(gitRoot);
+  }
+
+  return { gitRoot };
+}
+
+// ── update check ────────────────────────────────────────────
+
+function checkForUpdates() {
+  const notifier = updateNotifier({ pkg, updateCheckInterval: 1000 * 60 * 60 * 24 });
+  notifier.notify({ isGlobal: true });
+}
+
+// ── git helpers ─────────────────────────────────────────────
+
+function findGitRoot() {
+  try {
+    const root = execSync('git rev-parse --show-toplevel', {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    return root;
+  } catch {
+    return null;
+  }
+}
+
+function validateReadMeRepo(gitRoot) {
+  // Check for a branch matching ^v[0-9] (e.g. v1, v2.0, etc.)
+  let branches;
+  try {
+    branches = execSync('git branch -a --format="%(refname:short)"', {
+      cwd: gitRoot,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+  } catch {
+    branches = '';
+  }
+
+  const hasVersionBranch = branches
+    .split('\n')
+    .some((b) => /^(origin\/)?v[0-9]/.test(b.trim()));
+
+  // Check for /docs or /reference at the repo root
+  const hasDocs = fs.existsSync(path.join(gitRoot, 'docs'));
+  const hasReference = fs.existsSync(path.join(gitRoot, 'reference'));
+
+  if (!hasVersionBranch || (!hasDocs && !hasReference)) {
+    styles.error('This doesn\'t look like a ReadMe docs repo.');
+
+    if (!hasVersionBranch) {
+      styles.info(
+        `We couldn't find a version branch (e.g. ${styles.bold('v1')}, ${styles.bold('v2')}).`
+      );
+    }
+    if (!hasDocs && !hasReference) {
+      styles.info(
+        `We couldn't find a ${styles.bold('/docs')} or ${styles.bold('/reference')} folder.`
+      );
+    }
+
+    console.log();
+    styles.info('Make sure you\'re running this inside a ReadMe docs project.');
+    styles.info(`You can skip this check with ${styles.bold(`${styles.binName()} --no-check`)}.`);
+    process.exit(1);
+  }
+}

package/src/cli.js

@@ -0,0 +1,189 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { Command } from 'commander';
+import { createRequire } from 'node:module';
+import bootstrap from './bootstrap.js';
+import * as styles from './utils/styles.js';
+import { header, setPalette, isAgenticCli } from './utils/eyes.js';
+import { loadPet, applyDecay, getPetHeader } from './utils/tamagotchi.js';
+import { getRandomTip } from './utils/tips.js';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+
+const isRunningInClaude = isAgenticCli();
+
+export async function main() {
+  const program = new Command();
+
+  // Load tamagotchi state if it exists for personalized header
+  let petGreeting, petExpression;
+  let hasPet = false;
+  if (!isRunningInClaude) {
+    try {
+      const pet = loadPet();
+      if (pet) {
+        hasPet = true;
+        if (pet.color) setPalette(pet.color);
+        const updated = applyDecay(pet);
+        ({ greeting: petGreeting, expression: petExpression } = getPetHeader(updated));
+      }
+    } catch {
+      // No pet yet, use defaults
+    }
+  }
+
+  program
+    .name(styles.binName())
+    .version(pkg.version, '-v, --version')
+    .option('--no-check', 'Skip ReadMe project validation checks');
+
+  if (!isRunningInClaude) {
+    program.addHelpText('beforeAll', () => {
+      return '\n' + header({
+        version: pkg.version,
+        binName: styles.binName(),
+        greeting: petGreeting,
+        expression: petExpression,
+      }).map(l => '  ' + l).join('\n') + '\n';
+    });
+  }
+
+  // Auto-discover and register every command in src/commands/
+  const commandsDir = path.join(path.dirname(new URL(import.meta.url).pathname), 'commands');
+  const files = fs.readdirSync(commandsDir).filter((f) => f.endsWith('.js'));
+
+  // Load all modules, then sort by order (default 0)
+  const mods = [];
+  for (const file of files) {
+    const mod = await import(pathToFileURL(path.join(commandsDir, file)).href);
+    mods.push(mod);
+  }
+  mods.sort((a, b) => (a.order || 0) - (b.order || 0));
+
+  // Map of registered primary commands to their category, for the categorized
+  // help renderer below.
+  const commandCategories = new Map();
+
+  for (const mod of mods) {
+    const isPlay = mod.command === 'play';
+    const hidePlay = isPlay && (!hasPet || isRunningInClaude);
+    const cmd = program.command(mod.command, { hidden: !!((mod.hidden && !isPlay) || hidePlay) });
+
+    if (mod.description) {
+      const desc = mod.beta ? `${mod.description} ${styles.brand('[beta]')}` : mod.description;
+      cmd.description(desc);
+    }
+    if (mod.aliases) {
+      for (const alias of mod.aliases) {
+        const hidden = program.command(alias, { hidden: true });
+        if (mod.args) mod.args(hidden);
+        hidden.action(async (...args) => {
+          const ctx = await bootstrap({ skipValidation: !program.opts().check });
+          await mod.run(...args, ctx);
+        });
+      }
+    }
+    if (mod.args) mod.args(cmd); // let the command define its own arguments/options
+
+    cmd.action(async (...args) => {
+      if (mod.skipBootstrap) {
+        await mod.run(...args);
+      } else {
+        const ctx = await bootstrap({ skipValidation: !program.opts().check });
+        await mod.run(...args, ctx);
+      }
+    });
+
+    if (mod.category) commandCategories.set(cmd, mod.category);
+  }
+
+  // Suppress commander's auto-generated Commands: section — we render our own
+  // categorized version below via addHelpText('after').
+  program.configureHelp({ visibleCommands: () => [] });
+
+  program.addHelpText('after', () => {
+    // Group registered commands by category. The built-in `help` command
+    // doesn't go through the loop above, so we add it manually.
+    const groups = { 'Linting': [], 'OAS Tooling': [], 'Other': [] };
+    for (const [cmd, category] of commandCategories.entries()) {
+      if (cmd._hidden) continue;
+      if (!groups[category]) groups[category] = [];
+      groups[category].push(cmd);
+    }
+    // Commander's built-in help command isn't in program.commands — fetch via private getter.
+    const helpCmd = program._getHelpCommand && program._getHelpCommand();
+    if (helpCmd) groups['Other'].push(helpCmd);
+
+    const allCmds = Object.values(groups).flat();
+    if (allCmds.length === 0) return '';
+    const nameWidth = Math.max(...allCmds.map((c) => c.name().length));
+
+    // Map cmd → its source module so we can pull optional helpHint.
+    const cmdToMod = new Map();
+    for (const mod of mods) {
+      const cmd = program.commands.find((c) => c.name() === mod.command);
+      if (cmd) cmdToMod.set(cmd, mod);
+    }
+
+    const lines = [''];
+    for (const [category, cmds] of Object.entries(groups)) {
+      if (cmds.length === 0) continue;
+      lines.push(`${styles.bold(`${category} Commands:`)}`);
+      for (const cmd of cmds) {
+        const name = cmd.name().padEnd(nameWidth);
+        const desc = cmd.description() || '';
+        lines.push(`  ${name}  ${desc}`);
+        const hint = cmdToMod.get(cmd)?.helpHint;
+        if (hint) {
+          for (const hintLine of hint.split('\n')) {
+            lines.push(`  ${' '.repeat(nameWidth)}  ${styles.dim(hintLine)}`);
+          }
+        }
+      }
+      lines.push('');
+    }
+    return lines.join('\n').trimEnd();
+  });
+
+  // Show a random tip after help
+  program.addHelpText('afterAll', () => {
+    const tip = getRandomTip({ command: 'help' });
+    if (tip) {
+      let output = '';
+      const origLog = console.log;
+      console.log = (...args) => { output += args.join(' ') + '\n'; };
+      tip.render();
+      console.log = origLog;
+      return '\n' + output;
+    }
+    return '';
+  });
+
+  // Friendly fallback for unknown commands
+  program.on('command:*', ([cmd]) => {
+    styles.error(`Unknown command: ${styles.bold(cmd)}`);
+    styles.info(`Run ${styles.binName()} --help to see available commands.`);
+    process.exit(1);
+  });
+
+  // Show help if no command given
+  if (process.argv.length <= 2) {
+    program.outputHelp();
+    return;
+  }
+
+  // Support colon syntax (e.g. "eyes:right" → "eyes right"). Find the first
+  // non-flag positional so global options like --no-check don't bypass the rewrite.
+  const argv = [...process.argv];
+  let cmdIdx = 2;
+  while (cmdIdx < argv.length && argv[cmdIdx].startsWith('-')) cmdIdx++;
+  const cmdArg = argv[cmdIdx];
+  if (cmdArg && cmdArg.includes(':') && !program.commands.some((c) => c.name() === cmdArg)) {
+    const [base, ...rest] = cmdArg.split(':');
+    argv.splice(cmdIdx, 1, base, rest.join(':'));
+  }
+
+  await program.parseAsync(argv);
+}

package/src/commands/dev.js

@@ -0,0 +1,119 @@
+import fs from 'fs';
+import path from 'path';
+import { createServer } from 'http';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'node:module';
+import chalk from 'chalk';
+import { binName } from '../utils/styles.js';
+import { header, setPalette, isAgenticCli } from '../utils/eyes.js';
+import { loadPet } from '../utils/tamagotchi.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const command = 'dev';
+export const order = 6;
+export const category = 'Other';
+export const description = 'Start a local dev server to preview your docs';
+export const beta = true;
+
+export function args(cmd) {
+  cmd.option('--port <number>', 'Port to run the dev server on');
+}
+
+export async function run(options, _cmd, ctx) {
+  const { gitRoot } = ctx;
+
+  process.env.DOCS_ROOT = gitRoot;
+  process.env.NEXT_TELEMETRY_DISABLED = '1';
+
+  const devDir = path.join(__dirname, '..', 'dev');
+
+  const require = createRequire(import.meta.url);
+  const pkg = require('../../package.json');
+
+  // Load pet palette if available
+  try {
+    const pet = loadPet();
+    if (pet?.color) setPalette(pet.color);
+  } catch {}
+
+  // Suppress Next.js noisy compile/request logging
+  for (const stream of [process.stdout, process.stderr]) {
+    const original = stream.write.bind(stream);
+    stream.write = (chunk, ...args) => {
+      const str = typeof chunk === 'string' ? chunk : chunk.toString();
+      if (/^ [○✓⨯▲ ]*(Compiled|Compiling|GET |POST |⚠|Warning:)/.test(str)) return true;
+      return original(chunk, ...args);
+    };
+  }
+
+  const next = (await import('next')).default;
+  const app = next({ dev: true, dir: devDir, quiet: true });
+  await app.prepare();
+
+  const handle = app.getRequestHandler();
+
+  // SSE clients for live reload
+  const reloadClients = new Set();
+
+  const server = createServer((req, res) => {
+    if (req.url === '/__reload') {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        Connection: 'keep-alive',
+      });
+      res.write('data: connected\n\n');
+      reloadClients.add(res);
+      req.on('close', () => reloadClients.delete(res));
+      return;
+    }
+    handle(req, res);
+  });
+
+  // Watch for .md / .yaml file changes and notify browsers
+  fs.watch(gitRoot, { recursive: true }, (_event, filename) => {
+    if (filename && (filename.endsWith('.md') || filename.endsWith('.yaml'))) {
+      for (const client of reloadClients) {
+        client.write('data: reload\n\n');
+      }
+    }
+  });
+
+  const startPort = options.port ? parseInt(options.port, 10) : 4523;
+
+  function listen(port) {
+    return new Promise((resolve, reject) => {
+      const onError = (err) => {
+        if (err.code === 'EADDRINUSE') {
+          resolve(listen(port + 1));
+        } else {
+          reject(err);
+        }
+      };
+      server.once('error', onError);
+      server.listen(port, () => {
+        server.removeListener('error', onError);
+        resolve(port);
+      });
+    });
+  }
+
+  const port = await listen(startPort);
+
+  console.log();
+  if (!isAgenticCli()) {
+    const headerLines = header({
+      version: pkg.version,
+      binName: `${binName()} dev`,
+    });
+    for (const line of headerLines) {
+      console.log('  ' + line);
+    }
+    console.log();
+  }
+  console.log(`  Dev server is running!`);
+  console.log(`  ${chalk.dim('Changes to your files will auto-reload.')}`);
+  console.log(`  ${chalk.dim('→')} ${chalk.cyan(`http://localhost:${port}`)}`);
+  console.log();
+}

package/src/commands/eyes.js

@@ -0,0 +1,37 @@
+import { createRequire } from 'node:module';
+import { printEyes, animate, expressions, animations } from '../utils/eyes.js';
+import { binName } from '../utils/styles.js';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../../package.json');
+
+export const command = 'eyes [variant]';
+export const hidden = true;
+export const skipBootstrap = true;
+
+export async function run(variant) {
+  if (!variant) {
+    // Show all expressions side by side
+    const chalk = (await import('chalk')).default;
+    const names = Object.keys(expressions);
+    const rendered = Object.fromEntries(names.map(n => [n, expressions[n] ? require : null]));
+
+    console.log('');
+    const ctrl = animate('all', { indent: '  ', version: pkg.version, binName: binName() });
+    process.on('SIGINT', () => { ctrl.stop(); process.exit(); });
+    return;
+  }
+
+  if (expressions[variant]) {
+    console.log('');
+    printEyes(variant, '  ');
+    console.log('');
+  } else if (animations[variant]) {
+    console.log('');
+    const ctrl = animate(variant, { indent: '  ', version: pkg.version, binName: binName() });
+    process.on('SIGINT', () => { ctrl.stop(); process.exit(); });
+  } else {
+    console.error(`Unknown: "${variant}". Try: ${[...Object.keys(expressions), ...Object.keys(animations)].join(', ')}`);
+    process.exit(1);
+  }
+}