@readme/cli 0.1.0 → 0.2.0

package/bin/readme.js

@@ -2,7 +2,7 @@
 
 import { main } from '../src/cli.js';
 
-main().catch((err) => {
+main().catch(err => {
   console.error(err);
   process.exit(1);
 });

package/package.json

@@ -1,12 +1,24 @@
 {
   "name": "@readme/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The ReadMe CLI",
-  "type": "module",
+  "keywords": [
+    "cli",
+    "docs",
+    "readme"
+  ],
+  "license": "ISC",
   "bin": {
     "readme": "./bin/readme.js",
     "readme_": "./bin/readme.js"
   },
+  "files": [
+    "bin",
+    "src",
+    "vendor",
+    "README.md"
+  ],
+  "type": "module",
   "exports": {
     ".": "./src/index.js",
     "./commands/lint": "./src/commands/lint.js",
@@ -17,30 +29,18 @@
     "./prompts": "./src/prompts/index.js",
     "./package.json": "./package.json"
   },
-  "files": [
-    "bin",
-    "src",
-    "vendor",
-    "README.md"
-  ],
-  "scripts": {
-    "start": "node bin/readme.js",
-    "test": "node --test src/**/*.test.js test/*.test.js",
-    "build:gha": "ncc build src/gha.js -o dist-gha --external @readme/markdown"
-  },
-  "engines": {
-    "node": ">=22"
-  },
-  "keywords": [
-    "readme",
-    "cli",
-    "docs"
-  ],
-  "license": "ISC",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
+  "scripts": {
+    "build:gha": "ncc build src/gha.js -o dist-gha --external @readme/markdown",
+    "format": "npx oxlint --fix && npx oxfmt --write",
+    "lint": "npx oxlint && npx oxfmt --check .",
+    "pretest": "npm run lint",
+    "start": "node bin/readme.js",
+    "test": "vitest run"
+  },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.207",
     "@readme/markdown": "^13.3.0",
@@ -50,16 +50,25 @@
     "chalk": "^5.4.1",
     "cli-spinners": "^3.4.0",
     "commander": "^13.1.0",
-    "gray-matter": "^4.0.3",
+    "js-yaml": "^5.5.0",
     "log-update": "^8.0.0",
     "next": "^15.0.0",
     "oas-normalize": "^15.7.1",
     "ora": "^9.3.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
+    "remove-undefined-objects": "^9.0.0",
     "update-notifier": "^7.3.1"
   },
   "devDependencies": {
-    "@vercel/ncc": "^0.45.0"
+    "@readme/oxlint-config": "^1.9.0",
+    "@vercel/ncc": "^0.45.0",
+    "@vitest/coverage-v8": "^5.0.5",
+    "oxfmt": "^0.74.0",
+    "oxlint": "^1.89.0",
+    "vitest": "^5.0.5"
+  },
+  "engines": {
+    "node": ">=22"
   }
 }

package/src/bootstrap.js

@@ -1,8 +1,10 @@
 import { execSync } from 'node:child_process';
 import fs from 'node:fs';
-import path from 'node:path';
 import { createRequire } from 'node:module';
+import path from 'node:path';
+
 import updateNotifier from 'update-notifier';
+
 import * as styles from './utils/styles.js';
 
 const require = createRequire(import.meta.url);
@@ -22,7 +24,7 @@ export default async function bootstrap({ skipValidation = false } = {}) {
   // 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.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);
@@ -67,30 +69,24 @@ function validateReadMeRepo(gitRoot) {
     branches = '';
   }
 
-  const hasVersionBranch = branches
-    .split('\n')
-    .some((b) => /^(origin\/)?v[0-9]/.test(b.trim()));
+  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.');
+    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')}).`
-      );
+      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.`
-      );
+      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("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

@@ -1,12 +1,14 @@
 import fs from 'node:fs';
+import { createRequire } from 'node:module';
 import path from 'node:path';
 import { pathToFileURL, fileURLToPath } from 'node:url';
+
 import { Command } from 'commander';
-import { createRequire } from 'node:module';
 import updateNotifier from 'update-notifier';
+
 import bootstrap from './bootstrap.js';
-import * as styles from './utils/styles.js';
 import { header, setPalette, isAgenticCli } from './utils/eyes.js';
+import * as styles from './utils/styles.js';
 import { loadPet, applyDecay, getPetHeader } from './utils/tamagotchi.js';
 import { getRandomTip } from './utils/tips.js';
 
@@ -46,18 +48,20 @@ export async function main() {
 
   if (!isRunningInClaude) {
     program.addHelpText('beforeAll', () => {
-      return '\n' + header({
+      return `\n${header({
         version: pkg.version,
         binName: styles.binName(),
         greeting: petGreeting,
         expression: petExpression,
-      }).map(l => '  ' + l).join('\n') + '\n';
+      })
+        .map(l => `  ${l}`)
+        .join('\n')}\n`;
     });
   }
 
   // Auto-discover and register every command in src/commands/
   const commandsDir = path.join(path.dirname(fileURLToPath(import.meta.url)), 'commands');
-  const files = fs.readdirSync(commandsDir).filter((f) => f.endsWith('.js') && !f.endsWith('.test.js'));
+  const files = fs.readdirSync(commandsDir).filter(f => f.endsWith('.js') && !f.endsWith('.test.js'));
 
   // Load all modules, then sort by order (default 0)
   const mods = [];
@@ -111,7 +115,7 @@ export async function main() {
   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': [] };
+    const groups = { Linting: [], 'OAS Tooling': [], Other: [] };
     for (const [cmd, category] of commandCategories.entries()) {
       if (cmd._hidden) continue;
       if (!groups[category]) groups[category] = [];
@@ -123,12 +127,12 @@ export async function main() {
 
     const allCmds = Object.values(groups).flat();
     if (allCmds.length === 0) return '';
-    const nameWidth = Math.max(...allCmds.map((c) => c.name().length));
+    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);
+      const cmd = program.commands.find(c => c.name() === mod.command);
       if (cmd) cmdToMod.set(cmd, mod);
     }
 
@@ -158,10 +162,12 @@ export async function main() {
     if (tip) {
       let output = '';
       const origLog = console.log;
-      console.log = (...args) => { output += args.join(' ') + '\n'; };
+      console.log = (...args) => {
+        output += `${args.join(' ')}\n`;
+      };
       tip.render();
       console.log = origLog;
-      return '\n' + output;
+      return `\n${output}`;
     }
     return '';
   });
@@ -185,7 +191,7 @@ export async function main() {
   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)) {
+  if (cmdArg && cmdArg.includes(':') && !program.commands.some(c => c.name() === cmdArg)) {
     const [base, ...rest] = cmdArg.split(':');
     argv.splice(cmdIdx, 1, base, rest.join(':'));
   }

package/src/commands/components.js

@@ -13,9 +13,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
-import ora from 'ora';
+
 import { query } from '@anthropic-ai/claude-agent-sdk';
-import * as styles from '../utils/styles.js';
+import ora from 'ora';
+
+import { stripCodeFences } from '../prompts/index.js';
 import {
   listMarketplaceComponents,
   fetchMarketplaceComponent,
@@ -23,7 +25,7 @@ import {
   localComponentsDir,
   listLocalComponents,
 } from '../utils/marketplace.js';
-import { stripCodeFences } from '../prompts/index.js';
+import * as styles from '../utils/styles.js';
 
 export const command = 'components [action] [name...]';
 export const order = 3;
@@ -33,7 +35,7 @@ export const beta = true;
 export const helpHint = [
   'readme components               # list marketplace + installed',
   'readme components add <Name>    # copy a marketplace component into ./components/',
-  'readme components show <Name>   # print the component\'s source',
+  "readme components show <Name>   # print the component's source",
   'readme components new "<idea>"  # ask Claude to generate a new component',
 ].join('\n');
 
@@ -46,7 +48,7 @@ export function args(cmd) {
 export async function run(action, names, options, _cmd, ctx) {
   const { gitRoot } = ctx;
   const sub = (action || 'list').toLowerCase();
-  const arg = (names && names.length) ? names.join(' ') : null;
+  const arg = names && names.length ? names.join(' ') : null;
 
   switch (sub) {
     case 'list':
@@ -107,9 +109,9 @@ async function runList(gitRoot, options) {
   }
   spinner.stop();
 
-  const local = new Set(listLocalComponents(gitRoot).map((c) => c.name.toLowerCase()));
+  const local = new Set(listLocalComponents(gitRoot).map(c => c.name.toLowerCase()));
 
-  const nameWidth = Math.max(...marketplace.map((c) => c.name.length));
+  const nameWidth = Math.max(...marketplace.map(c => c.name.length));
   for (const c of marketplace) {
     const installed = local.has(c.name.toLowerCase());
     const marker = installed ? styles.success('●') : styles.dim('○');
@@ -118,7 +120,7 @@ async function runList(gitRoot, options) {
   }
 
   console.log();
-  const installedCount = [...local].filter((n) => marketplace.some((c) => c.name.toLowerCase() === n)).length;
+  const installedCount = [...local].filter(n => marketplace.some(c => c.name.toLowerCase() === n)).length;
   styles.info(`${marketplace.length} components in the marketplace · ${installedCount} already installed.`);
   styles.info(`Run ${styles.bold('readme components add <Name>')} to copy one into ./components/.`);
 }
@@ -173,12 +175,22 @@ async function runShow(name, options) {
   console.log(`  ${styles.heading(comp.name)}  ${styles.dim(comp.htmlUrl)}`);
   if (comp.readme) {
     console.log();
-    console.log(comp.readme.split('\n').map((l) => '  ' + l).join('\n'));
+    console.log(
+      comp.readme
+        .split('\n')
+        .map(l => `  ${l}`)
+        .join('\n'),
+    );
   }
   console.log();
   console.log(`  ${styles.bold('Source')} ${styles.dim(`(${comp.name}.mdx)`)}`);
   console.log();
-  console.log(comp.mdx.split('\n').map((l) => '    ' + l).join('\n'));
+  console.log(
+    comp.mdx
+      .split('\n')
+      .map(l => `    ${l}`)
+      .join('\n'),
+  );
   console.log();
 }
 
@@ -198,7 +210,9 @@ async function runNew(gitRoot, description, options) {
     try {
       const c = await fetchMarketplaceComponent(n);
       exemplars.push({ name: c.name, mdx: c.mdx });
-    } catch { /* skip */ }
+    } catch {
+      /* skip */
+    }
   }
 
   const systemPrompt = [
@@ -221,7 +235,7 @@ async function runNew(gitRoot, description, options) {
     '',
     'For style and conventions, follow these existing components (do NOT copy them — match their structure):',
     '',
-    ...exemplars.map((e) => `### ${e.name}\n\`\`\`mdx\n${e.mdx}\n\`\`\``),
+    ...exemplars.map(e => `### ${e.name}\n\`\`\`mdx\n${e.mdx}\n\`\`\``),
     '',
     'Now write the new component .mdx. Pick a good PascalCase name that matches the brief.',
   ].join('\n');
@@ -243,7 +257,7 @@ async function runNew(gitRoot, description, options) {
         }
       } else if (message.type === 'result') {
         if (message.subtype && message.subtype !== 'success') {
-          throw new Error(`${message.subtype}${message.error?.message ? ' — ' + message.error.message : ''}`);
+          throw new Error(`${message.subtype}${message.error?.message ? ` — ${message.error.message}` : ''}`);
         }
         break;
       }
@@ -258,7 +272,7 @@ async function runNew(gitRoot, description, options) {
   const mdx = stripCodeFences(text).trim();
   const nameMatch = mdx.match(/export\s+const\s+([A-Z][A-Za-z0-9]+)\s*=/);
   if (!nameMatch) {
-    styles.error('Claude\'s response did not include `export const <Name> = ...`. Try again.');
+    styles.error("Claude's response did not include `export const <Name> = ...`. Try again.");
     process.exit(1);
   }
 
@@ -266,10 +280,13 @@ async function runNew(gitRoot, description, options) {
   const file = path.join(dest, `${name}.mdx`);
   if (fs.existsSync(file) && !options.yes) {
     const ok = await confirm(`${styles.bold(name)}.mdx already exists. Overwrite?`);
-    if (!ok) { styles.info('Aborted.'); return; }
+    if (!ok) {
+      styles.info('Aborted.');
+      return;
+    }
   }
 
-  fs.writeFileSync(file, mdx + '\n', 'utf-8');
+  fs.writeFileSync(file, `${mdx}\n`, 'utf-8');
   console.log();
   styles.ok(`Created ${styles.bold(name)} → ${styles.dim(path.relative(gitRoot, file))}`);
   styles.info(`Use it in any docs page as ${styles.bold(`<${name} ... />`)}.`);
@@ -278,9 +295,9 @@ async function runNew(gitRoot, description, options) {
 // ─── tiny readline confirm ───────────────────────────────────────────────────
 
 function confirm(message) {
-  return new Promise((resolve) => {
+  return new Promise(resolve => {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    rl.question(`${styles.warn('?')} ${message} ${styles.dim('[y/N]')} `, (ans) => {
+    rl.question(`${styles.warn('?')} ${message} ${styles.dim('[y/N]')} `, ans => {
       rl.close();
       resolve(/^y(es)?$/i.test(ans.trim()));
     });

package/src/commands/dev.js

@@ -1,11 +1,13 @@
 import fs from 'fs';
-import path from 'path';
 import { createServer } from 'http';
-import { fileURLToPath } from 'url';
 import { createRequire } from 'node:module';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
 import chalk from 'chalk';
-import { binName } from '../utils/styles.js';
+
 import { header, setPalette, isAgenticCli } from '../utils/eyes.js';
+import { binName } from '../utils/styles.js';
 import { loadPet } from '../utils/tamagotchi.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -35,15 +37,17 @@ export async function run(options, _cmd, ctx) {
   try {
     const pet = loadPet();
     if (pet?.color) setPalette(pet.color);
-  } catch {}
+  } catch {
+    // no-op
+  }
 
   // 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) => {
+    stream.write = (chunk, ...streamAgs) => {
       const str = typeof chunk === 'string' ? chunk : chunk.toString();
       if (/^ [○✓⨯▲ ]*(Compiled|Compiling|GET |POST |⚠|Warning:)/.test(str)) return true;
-      return original(chunk, ...args);
+      return original(chunk, ...streamAgs);
     };
   }
 
@@ -84,7 +88,7 @@ export async function run(options, _cmd, ctx) {
 
   function listen(port) {
     return new Promise((resolve, reject) => {
-      const onError = (err) => {
+      const onError = err => {
         if (err.code === 'EADDRINUSE') {
           resolve(listen(port + 1));
         } else {
@@ -108,7 +112,7 @@ export async function run(options, _cmd, ctx) {
       binName: `${binName()} dev`,
     });
     for (const line of headerLines) {
-      console.log('  ' + line);
+      console.log(`  ${line}`);
     }
     console.log();
   }

package/src/commands/eyes.js

@@ -1,4 +1,5 @@
 import { createRequire } from 'node:module';
+
 import { printEyes, animate, expressions, animations } from '../utils/eyes.js';
 import { binName } from '../utils/styles.js';
 
@@ -11,14 +12,12 @@ 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(); });
+    process.on('SIGINT', () => {
+      ctrl.stop();
+      process.exit();
+    });
     return;
   }
 
@@ -29,9 +28,14 @@ export async function run(variant) {
   } else if (animations[variant]) {
     console.log('');
     const ctrl = animate(variant, { indent: '  ', version: pkg.version, binName: binName() });
-    process.on('SIGINT', () => { ctrl.stop(); process.exit(); });
+    process.on('SIGINT', () => {
+      ctrl.stop();
+      process.exit();
+    });
   } else {
-    console.error(`Unknown: "${variant}". Try: ${[...Object.keys(expressions), ...Object.keys(animations)].join(', ')}`);
+    console.error(
+      `Unknown: "${variant}". Try: ${[...Object.keys(expressions), ...Object.keys(animations)].join(', ')}`,
+    );
     process.exit(1);
   }
 }