@readme/cli 0.0.26

package/src/commands/lint.js

@@ -0,0 +1,70 @@
+import { createRequire } from 'node:module';
+import { collectFiles, runValidators } from '../utils/lint.js';
+import { createHumanReporter, createJsonReporter, createGithubReporter } from '../utils/reporter.js';
+import { printHeader, isAgenticCli } from '../utils/eyes.js';
+import * as styles from '../utils/styles.js';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../../package.json');
+
+export const command = 'lint';
+export const order = 1;
+export const aliases = ['validate'];
+export const category = 'Linting';
+export const description = 'Lint and validate your ReadMe docs';
+
+export function args(cmd) {
+  cmd.option('--json', 'Output results as JSON (for CI and automation)');
+  cmd.option('--github', 'Output a GitHub PR comment body as markdown');
+  cmd.option('--fix', 'Automatically fix issues where possible');
+}
+
+/**
+ * Run the linter programmatically. Returns the collected files and validator
+ * results with no console output and no process.exit — callers can format and
+ * exit on their own terms.
+ *
+ * @param {object}  [opts]
+ * @param {string}  [opts.cwd]   Repo root to lint (defaults to process.cwd()).
+ * @param {boolean} [opts.fix]   Apply autofixes where validators support it.
+ * @param {(file: string) => void} [opts.onFile]            Called per file before validation.
+ * @param {() => void}             [opts.onBeforeCrossFile] Called once before cross-file checks run.
+ * @returns {Promise<{ gitRoot: string, files: string[], results: object[], hasErrors: boolean }>}
+ */
+export async function lint({ cwd, fix = false, onFile, onBeforeCrossFile } = {}) {
+  const gitRoot = cwd || process.cwd();
+  const files = collectFiles(gitRoot);
+  const results = await runValidators(files, gitRoot, { onFile, onBeforeCrossFile, fix });
+  const hasErrors = results.some((r) => r.severity !== 'warning');
+  return { gitRoot, files, results, hasErrors };
+}
+
+export async function run(options, _cmd, ctx) {
+  const { gitRoot } = ctx;
+
+  if (!options.json && !options.github && !isAgenticCli()) {
+    printHeader({ version: pkg.version, binName: styles.binName(), indent: '  ' });
+    console.log();
+  }
+
+  const reporter = options.github
+    ? createGithubReporter()
+    : options.json
+      ? createJsonReporter()
+      : createHumanReporter();
+
+  const { files, results, hasErrors } = await lint({
+    cwd: gitRoot,
+    fix: options.fix,
+    onFile: (f) => reporter.onFile(f),
+    onBeforeCrossFile: () => reporter.pause(),
+  });
+
+  reporter.finish(files.length, results, files, { fix: options.fix, gitRoot });
+
+  if (hasErrors) {
+    // Wait for stdout to flush (important when piped to a file), then exit
+    await new Promise((resolve) => process.stdout.write('', resolve));
+    process.exit(1);
+  }
+}

package/src/commands/oas-sync.js

@@ -0,0 +1,364 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import matter from 'gray-matter';
+import * as styles from '../utils/styles.js';
+
+const require = createRequire(import.meta.url);
+const yaml = require('js-yaml');
+
+export const command = 'oas:sync';
+export const order = 2;
+export const category = 'OAS Tooling';
+export const description = 'Sync reference pages with OpenAPI specs';
+
+const HTTP_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'trace']);
+
+/**
+ * Check if this is a ReadMeConfig spec (internal ReadMe pages — skip title/excerpt updates).
+ */
+function isReadMeConfig(spec) {
+  return spec.info?.title === 'ReadMeConfig';
+}
+
+/**
+ * Find OAS files at the root of reference/ (JSON or YAML).
+ */
+export function findOasFiles(refDir) {
+  const entries = fs.readdirSync(refDir);
+  const oasFiles = [];
+
+  for (const entry of entries) {
+    if (!/\.(json|yaml|yml)$/i.test(entry)) continue;
+    const filePath = path.join(refDir, entry);
+    if (!fs.statSync(filePath).isFile()) continue;
+
+    try {
+      const raw = fs.readFileSync(filePath, 'utf-8');
+      const parsed = entry.endsWith('.json') ? JSON.parse(raw) : yaml.load(raw);
+
+      if (parsed && (parsed.openapi || parsed.swagger)) {
+        oasFiles.push({ filename: entry, spec: parsed });
+      }
+    } catch {
+      // Skip files that can't be parsed.
+    }
+  }
+
+  return oasFiles;
+}
+
+/**
+ * Generate a synthetic operationId from the HTTP method and path.
+ * Matches the algorithm used by the `oas` package for specs without operationIds.
+ */
+function generateOperationId(method, pathStr) {
+  const sanitized = pathStr
+    .replace(/[^a-zA-Z0-9]/g, '-')
+    .replace(/--+/g, '-')
+    .replace(/^-|-$/g, '')
+    .toLowerCase();
+  return `${method.toLowerCase()}_${sanitized}`;
+}
+
+/**
+ * Extract operations from an OAS spec.
+ * Returns a Map of operationId -> { summary, description, tag, operationId }.
+ * For operations without an operationId, a synthetic one is generated from the method and path.
+ */
+export function extractOperations(spec) {
+  const ops = new Map();
+  const paths = spec.paths || {};
+
+  for (const [pathStr, methods] of Object.entries(paths)) {
+    for (const [method, operation] of Object.entries(methods)) {
+      if (!HTTP_METHODS.has(method)) continue;
+
+      const operationId = operation.operationId || generateOperationId(method, pathStr);
+
+      ops.set(operationId, {
+        operationId,
+        summary: operation.summary || null,
+        description: operation.description || null,
+        tag: (operation.tags && operation.tags[0]) || null,
+      });
+    }
+  }
+
+  return ops;
+}
+
+/**
+ * Scan existing .md files under reference/ recursively and collect those
+ * with api.file + api.operationId frontmatter.
+ */
+export function collectExistingPages(refDir) {
+  const pages = [];
+
+  function walk(dir) {
+    for (const entry of fs.readdirSync(dir)) {
+      const full = path.join(dir, entry);
+      const stat = fs.statSync(full);
+      if (stat.isDirectory()) {
+        walk(full);
+      } else if (entry.endsWith('.md')) {
+        try {
+          const content = fs.readFileSync(full, 'utf-8');
+          const { data } = matter(content);
+          if (data.api && data.api.file && data.api.operationId) {
+            pages.push({
+              filePath: full,
+              relativePath: path.relative(refDir, full),
+              data,
+              content,
+            });
+          }
+        } catch {
+          // Skip unparseable files.
+        }
+      }
+    }
+  }
+
+  walk(refDir);
+  return pages;
+}
+
+// Values that YAML interprets as non-strings and need quoting in _order.yaml.
+const YAML_UNSAFE = /^(?:\d+\.?\d*|true|false|yes|no|on|off|null|~)$/i;
+function yamlSafeSlug(slug) {
+  return YAML_UNSAFE.test(slug) ? `"${slug}"` : slug;
+}
+
+function parseOrderYaml(content) {
+  return content
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith('- '))
+    .map((line) => line.slice(2).trim().replace(/^["'](.+)["']$/, '$1'));
+}
+
+function writeOrderYaml(filePath, slugs) {
+  const content = slugs.map((s) => `- ${yamlSafeSlug(s)}`).join('\n') + '\n';
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+}
+
+function addToOrder(orderPath, slug) {
+  if (fs.existsSync(orderPath)) {
+    const content = fs.readFileSync(orderPath, 'utf-8');
+    const slugs = parseOrderYaml(content);
+    if (!slugs.includes(slug)) {
+      slugs.push(slug);
+      writeOrderYaml(orderPath, slugs);
+    }
+  } else {
+    writeOrderYaml(orderPath, [slug]);
+  }
+}
+
+function removeFromOrder(orderPath, slug) {
+  if (!fs.existsSync(orderPath)) return;
+  const content = fs.readFileSync(orderPath, 'utf-8');
+  const slugs = parseOrderYaml(content).filter((s) => s !== slug);
+  if (slugs.length > 0) {
+    writeOrderYaml(orderPath, slugs);
+  } else {
+    fs.unlinkSync(orderPath);
+  }
+}
+
+function buildPageContent({ oasFilename, operationId, summary, description }) {
+  const frontmatter = {
+    title: summary || operationId,
+    api: {
+      file: oasFilename,
+      operationId,
+    },
+  };
+
+  if (description) {
+    frontmatter.excerpt = description;
+  }
+
+  return matter.stringify('', frontmatter);
+}
+
+/**
+ * Run the sync for a single OAS file. Returns changes for that file.
+ */
+function syncOneOas(refDir, oasFilename, spec) {
+  const specOps = extractOperations(spec);
+  const infoTitle = spec.info?.title || path.basename(oasFilename, path.extname(oasFilename));
+  const skipUpdates = isReadMeConfig(spec);
+
+  const existingPages = collectExistingPages(refDir).filter(
+    (p) => p.data.api.file === oasFilename,
+  );
+
+  const pagesByOpId = new Map();
+  for (const page of existingPages) {
+    pagesByOpId.set(page.data.api.operationId, page);
+  }
+
+  const changes = { added: [], deleted: [], updated: [] };
+
+  // Deletes: pages referencing operations that no longer exist.
+  for (const [opId, page] of pagesByOpId) {
+    if (!specOps.has(opId)) {
+      fs.unlinkSync(page.filePath);
+
+      const pageDir = path.dirname(page.filePath);
+      const slug = path.basename(page.filePath, '.md');
+      removeFromOrder(path.join(pageDir, '_order.yaml'), slug);
+
+      changes.deleted.push(page.relativePath);
+    }
+  }
+
+  // Adds + Updates.
+  for (const [opId, op] of specOps) {
+    const existing = pagesByOpId.get(opId);
+    const tag = op.tag || 'Other';
+
+    if (!existing) {
+      const pageDir = path.join(refDir, infoTitle, tag);
+      fs.mkdirSync(pageDir, { recursive: true });
+
+      const pagePath = path.join(pageDir, `${opId}.md`);
+      const content = buildPageContent({
+        oasFilename,
+        operationId: opId,
+        summary: op.summary,
+        description: op.description,
+      });
+      fs.writeFileSync(pagePath, content);
+
+      addToOrder(path.join(pageDir, '_order.yaml'), opId);
+      addToOrder(path.join(refDir, infoTitle, '_order.yaml'), tag);
+
+      changes.added.push(path.relative(refDir, pagePath));
+    } else if (!skipUpdates) {
+      const expectedTitle = op.summary || opId;
+      const expectedExcerpt = op.description || null;
+      const currentTitle = existing.data.title;
+      const currentExcerpt = existing.data.excerpt || null;
+
+      const titleChanged = currentTitle !== expectedTitle;
+      const excerptChanged = currentExcerpt !== expectedExcerpt;
+
+      if (titleChanged || excerptChanged) {
+        const updated = { ...existing.data };
+        const updateDetails = [];
+
+        if (titleChanged) {
+          updated.title = expectedTitle;
+          updateDetails.push('title');
+        }
+        if (excerptChanged) {
+          if (expectedExcerpt) {
+            updated.excerpt = expectedExcerpt;
+          } else {
+            delete updated.excerpt;
+          }
+          updateDetails.push('excerpt');
+        }
+
+        const body = matter(existing.content).content;
+        const newContent = matter.stringify(body, updated);
+        fs.writeFileSync(existing.filePath, newContent);
+
+        changes.updated.push(`${existing.relativePath} (${updateDetails.join(', ')})`);
+      }
+    }
+  }
+
+  return changes;
+}
+
+/**
+ * Sync reference pages with the OpenAPI spec(s) under `<gitRoot>/reference/`.
+ *
+ * Pure programmatic API: returns per-file change descriptors and prints
+ * nothing. Used by the CLI command, the lint --fix flow, and external
+ * callers.
+ *
+ * @param {string | { cwd?: string }} input  Repo root path, or `{ cwd }` object.
+ * @returns {null | Array<{ filename: string, spec: object, opCount: number,
+ *   changes: { added: string[], deleted: string[], updated: string[] } }>}
+ *   Returns null if there's no reference/ dir or no specs.
+ */
+export function syncOas(input) {
+  const gitRoot = typeof input === 'string' ? input : (input?.cwd || process.cwd());
+  const refDir = path.join(gitRoot, 'reference');
+  if (!fs.existsSync(refDir)) return null;
+
+  const oasFiles = findOasFiles(refDir);
+  if (oasFiles.length === 0) return null;
+
+  const allChanges = [];
+
+  for (const { filename, spec } of oasFiles) {
+    const ops = extractOperations(spec);
+    const changes = syncOneOas(refDir, filename, spec);
+    allChanges.push({ filename, spec, opCount: ops.size, changes });
+  }
+
+  return allChanges;
+}
+
+export async function run(_options, _cmd, ctx) {
+  const { gitRoot } = ctx;
+  const refDir = path.join(gitRoot, 'reference');
+
+  if (!fs.existsSync(refDir)) {
+    styles.error('No reference/ directory found.');
+    process.exit(1);
+  }
+
+  const results = syncOas(gitRoot);
+
+  if (!results) {
+    styles.info('No OpenAPI spec files found in reference/.');
+    return;
+  }
+
+  let totalAdded = 0;
+  let totalDeleted = 0;
+  let totalUpdated = 0;
+
+  for (const { filename, spec, opCount, changes } of results) {
+    const title = spec.info?.title || filename;
+    const hasChanges = changes.added.length + changes.deleted.length + changes.updated.length > 0;
+
+    const dot = hasChanges ? styles.warn('●') : styles.success('●');
+    console.log();
+    console.log(`  ${dot} ${styles.bold(title)} ${styles.dim(`(${filename} · ${opCount} ${opCount === 1 ? 'endpoint' : 'endpoints'})`)}`);
+
+    if (!hasChanges) {
+      continue;
+    }
+
+    for (const file of changes.added) {
+      console.log(`    ${styles.success('+')} Added ${file}`);
+    }
+    for (const file of changes.deleted) {
+      console.log(`    ${styles.err('−')} Deleted ${file}`);
+    }
+    for (const file of changes.updated) {
+      console.log(`    ${styles.warn('~')} Updated ${file}`);
+    }
+
+    totalAdded += changes.added.length;
+    totalDeleted += changes.deleted.length;
+    totalUpdated += changes.updated.length;
+  }
+
+  console.log();
+  const total = totalAdded + totalDeleted + totalUpdated;
+  if (total === 0) {
+    styles.ok('Reference pages are already in sync.');
+  } else {
+    styles.ok(`Synced: ${totalAdded} added, ${totalDeleted} deleted, ${totalUpdated} updated.`);
+  }
+}

package/src/commands/oas-validate.js

@@ -0,0 +1,208 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import OASNormalize from 'oas-normalize';
+import { findOasFiles, extractOperations } from './oas-sync.js';
+import * as styles from '../utils/styles.js';
+
+export const command = 'oas:validate';
+export const order = 3;
+export const category = 'OAS Tooling';
+export const description = 'Validate OpenAPI spec files';
+
+export function args(cmd) {
+  cmd.option('--dereference', 'Also dereference all $ref pointers (matches ReadMe server validation)');
+}
+
+/**
+ * Walk a parsed spec object and find $ref values that look malformed.
+ * Valid internal refs start with "#/", valid external refs don't start with "#".
+ * Catches things like "#components/schemas/Foo" (missing the slash after #).
+ */
+function findBadRefs(obj, pointer = '') {
+  const issues = [];
+  if (obj && typeof obj === 'object') {
+    if (typeof obj.$ref === 'string') {
+      const ref = obj.$ref;
+      if (ref.startsWith('#') && !ref.startsWith('#/')) {
+        issues.push({ path: pointer, ref });
+      }
+    }
+    for (const [key, value] of Object.entries(obj)) {
+      if (key === '$ref') continue;
+      issues.push(...findBadRefs(value, `${pointer}/${key}`));
+    }
+  }
+  return issues;
+}
+
+const RULES = {
+  openapi: {
+    'array-without-items': 'warning',
+    'duplicate-non-request-body-parameters': 'warning',
+    'duplicate-operation-id': 'warning',
+    'non-optional-path-parameters': 'warning',
+    'path-parameters-not-in-parameters': 'warning',
+    'path-parameters-not-in-path': 'warning',
+  },
+  swagger: {
+    'array-without-items': 'warning',
+    'duplicate-non-request-body-parameters': 'warning',
+    'duplicate-operation-id': 'warning',
+    'non-optional-path-parameters': 'warning',
+    'path-parameters-not-in-parameters': 'warning',
+    'path-parameters-not-in-path': 'warning',
+    'unknown-required-schema-property': 'warning',
+  },
+};
+
+/**
+ * Validate all OAS files under `<gitRoot>/reference/`. Pure programmatic API:
+ * returns per-file results without printing or exiting.
+ *
+ * @param {object}  [opts]
+ * @param {string}  [opts.cwd]          Repo root (defaults to process.cwd()).
+ * @param {boolean} [opts.dereference]  Also dereference $ref pointers (matches ReadMe server validation).
+ * @returns {Promise<null | {
+ *   fileCount: number,
+ *   totalErrors: number,
+ *   totalWarnings: number,
+ *   totalValid: number,
+ *   results: Array<{
+ *     filename: string,
+ *     title: string,
+ *     version: string,
+ *     opCount: number,
+ *     errors: Array<{ message: string }>,
+ *     warnings: Array<{ message: string }>,
+ *     valid: boolean,
+ *   }>,
+ * }>}
+ *   Returns null if there's no reference/ dir or no spec files.
+ */
+export async function validateOas({ cwd, dereference = false } = {}) {
+  const gitRoot = cwd || process.cwd();
+  const refDir = path.join(gitRoot, 'reference');
+  if (!fs.existsSync(refDir)) return null;
+
+  const oasFiles = findOasFiles(refDir);
+  if (oasFiles.length === 0) return null;
+
+  const results = [];
+  let totalErrors = 0;
+  let totalWarnings = 0;
+  let totalValid = 0;
+
+  for (const { filename, spec } of oasFiles) {
+    const filePath = path.join(refDir, filename);
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const title = spec.info?.title || filename;
+    const version = spec.openapi || spec.swagger || 'unknown';
+    const opCount = extractOperations(spec).size;
+
+    let normalizerResult;
+    try {
+      const normalizer = new OASNormalize(raw, { enablePaths: false });
+      normalizerResult = await normalizer.validate({
+        shouldThrowIfInvalid: false,
+        parser: { validate: { rules: RULES } },
+      });
+    } catch (err) {
+      const errors = [{ message: err.message || String(err) }];
+      results.push({ filename, title, version, opCount, errors, warnings: [], valid: false });
+      totalErrors += 1;
+      continue;
+    }
+
+    const errors = normalizerResult.valid ? [] : (normalizerResult.errors || []);
+    const warnings = normalizerResult.warnings || [];
+
+    if (dereference) {
+      try {
+        const normalizer = new OASNormalize(raw, { enablePaths: false });
+        await normalizer.deref();
+      } catch (err) {
+        const msg = err.message || String(err);
+        errors.push({ message: `Dereference failed: ${msg}` });
+      }
+    }
+
+    // Catches malformed pointers like "#components/..." (missing slash) that
+    // oas-normalize accepts.
+    const badRefs = findBadRefs(spec);
+    for (const { path: refPath, ref } of badRefs) {
+      errors.push({ message: `Malformed $ref: "${ref}" at ${refPath} (should start with "#/")` });
+    }
+
+    totalErrors += errors.length;
+    totalWarnings += warnings.length;
+    const valid = errors.length === 0;
+    if (valid) totalValid += 1;
+
+    results.push({ filename, title, version, opCount, errors, warnings, valid });
+  }
+
+  return { fileCount: oasFiles.length, totalErrors, totalWarnings, totalValid, results };
+}
+
+/**
+ * Validate OAS files and print results (used by the CLI command).
+ * Returns the same aggregate shape `validateOas` does.
+ *
+ * @deprecated Prefer `validateOas` for programmatic use; this helper prints to
+ * stdout. Kept exported for backward compatibility.
+ */
+export async function validateOasFiles(gitRoot, { dereference = false } = {}) {
+  const summary = await validateOas({ cwd: gitRoot, dereference });
+  if (!summary) return null;
+
+  for (const r of summary.results) {
+    const meta = `${r.filename} · ${r.version} · ${r.opCount} ${r.opCount === 1 ? 'endpoint' : 'endpoints'}`;
+    const dot = r.errors.length > 0
+      ? styles.err('●')
+      : r.warnings.length > 0 ? styles.warn('●') : styles.success('●');
+
+    console.log();
+    console.log(`  ${dot} ${styles.bold(r.title)} ${styles.dim(`(${meta})`)}`);
+
+    if (r.errors.length === 0 && r.warnings.length === 0) {
+      console.log(`    ${styles.success('Valid')}`);
+      continue;
+    }
+    for (const e of r.errors) console.log(`    ${styles.err('✘')} ${e.message}`);
+    for (const w of r.warnings) console.log(`    ${styles.warn('⚠')} ${w.message}`);
+  }
+
+  const { totalErrors, totalWarnings, totalValid, fileCount } = summary;
+  return { totalErrors, totalWarnings, totalValid, fileCount };
+}
+
+export async function run(options, _cmd, ctx) {
+  const { gitRoot } = ctx;
+  const refDir = path.join(gitRoot, 'reference');
+
+  if (!fs.existsSync(refDir)) {
+    styles.error('No reference/ directory found.');
+    process.exit(1);
+  }
+
+  const result = await validateOasFiles(gitRoot, { dereference: options.dereference });
+
+  if (!result) {
+    styles.info('No OpenAPI spec files found in reference/.');
+    return;
+  }
+
+  const { totalErrors, totalWarnings, totalValid, fileCount } = result;
+
+  console.log();
+  if (totalErrors > 0) {
+    const parts = [`${totalErrors} ${totalErrors === 1 ? 'error' : 'errors'}`];
+    if (totalWarnings > 0) parts.push(`${totalWarnings} ${totalWarnings === 1 ? 'warning' : 'warnings'}`);
+    styles.error(`${parts.join(' and ')} across ${fileCount} ${fileCount === 1 ? 'spec' : 'specs'}.`);
+    process.exit(1);
+  } else if (totalWarnings > 0) {
+    styles.warning(`${totalValid} of ${fileCount} specs valid with ${totalWarnings} ${totalWarnings === 1 ? 'warning' : 'warnings'}.`);
+  } else {
+    styles.ok(`${fileCount} ${fileCount === 1 ? 'spec' : 'specs'} validated — all good!`);
+  }
+}

package/src/commands/play.js

@@ -0,0 +1,17 @@
+export const command = 'play';
+export const description = 'Visit your pet';
+export const hidden = true;
+export const skipBootstrap = true;
+export const order = 99;
+export const category = 'Other';
+
+export async function run(variant) {
+  if (variant === 'reset') {
+    const { resetPet } = await import('../utils/tamagotchi.js');
+    resetPet();
+    return;
+  }
+
+  const { startGame } = await import('../utils/tamagotchi.js');
+  await startGame();
+}