@readme/cli 0.0.26

package/src/commands/pretty.js

@@ -0,0 +1,133 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import matter from 'gray-matter';
+import ora from 'ora';
+import { collectFiles } from '../utils/lint.js';
+import { prettifyPagePrompt, stripCodeFences } from '../prompts/index.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 = 'pretty';
+export const order = 2;
+export const description = 'Polish docs into ReadMe-ready MDX with Claude';
+export const beta = true;
+
+export function args(cmd) {
+  cmd.option('--model <name>', 'Claude model alias: haiku, sonnet, opus', 'sonnet');
+  cmd.option('--dry-run', 'Show what would change without writing files');
+}
+
+/**
+ * Send one page through Claude using the prettify system prompt and parse the
+ * JSON response. Returns the parsed object or throws on failure.
+ */
+async function prettifyPage({ source, title, relativePath, model }) {
+  const { systemPrompt, userPrompt } = prettifyPagePrompt({ source, title, relativePath });
+
+  let text = '';
+  for await (const message of query({
+    prompt: userPrompt,
+    options: {
+      systemPrompt,
+      allowedTools: [],
+      ...(model ? { model } : {}),
+    },
+  })) {
+    if (message.type === 'assistant' && message.message?.content) {
+      for (const block of message.message.content) {
+        if (block.type === 'text' && block.text) text += block.text;
+      }
+    } else if (message.type === 'result') {
+      if (message.subtype && message.subtype !== 'success') {
+        throw new Error(`${message.subtype}${message.error?.message ? ' — ' + message.error.message : ''}`);
+      }
+      break;
+    }
+  }
+
+  const stripped = stripCodeFences(text);
+  try {
+    return JSON.parse(stripped);
+  } catch (e) {
+    throw new Error(`invalid JSON (${e.message}); first 200 chars: ${stripped.slice(0, 200)}`);
+  }
+}
+
+export async function run(options, _cmd, ctx) {
+  const { gitRoot } = ctx;
+
+  if (!isAgenticCli()) {
+    printHeader({ version: pkg.version, binName: styles.binName(), indent: '  ' });
+    console.log();
+  }
+
+  const files = collectFiles(gitRoot);
+  if (files.length === 0) {
+    styles.warning('No docs files found to prettify.');
+    return;
+  }
+
+  styles.info(
+    `Prettifying ${styles.bold(String(files.length))} file${files.length === 1 ? '' : 's'} with ${styles.bold(options.model)}${options.dryRun ? styles.dim(' (dry run)') : ''}.`,
+  );
+  console.log();
+
+  const spinner = ora({ color: 'blue' }).start();
+  let updated = 0;
+  let unchanged = 0;
+  const failures = [];
+
+  for (const relativePath of files) {
+    spinner.text = relativePath;
+    const filePath = path.join(gitRoot, relativePath);
+    const original = fs.readFileSync(filePath, 'utf-8');
+    const parsed = matter(original);
+
+    try {
+      const result = await prettifyPage({
+        source: parsed.content,
+        title: parsed.data?.title,
+        relativePath,
+        model: options.model,
+      });
+
+      if (typeof result?.body !== 'string') {
+        throw new Error('response missing "body" field');
+      }
+
+      const newFm = { ...parsed.data };
+      if (result.excerpt && !newFm.excerpt) newFm.excerpt = result.excerpt;
+      const next = matter.stringify(result.body, newFm);
+
+      if (next === original) {
+        unchanged++;
+      } else {
+        if (!options.dryRun) fs.writeFileSync(filePath, next, 'utf-8');
+        updated++;
+      }
+    } catch (err) {
+      failures.push({ relativePath, message: err.message || String(err) });
+    }
+  }
+
+  spinner.stop();
+
+  console.log();
+  const verb = options.dryRun ? 'would update' : 'updated';
+  styles.ok(
+    `${styles.bold(String(updated))} ${verb} · ${styles.bold(String(unchanged))} unchanged${failures.length ? ` · ${styles.bold(String(failures.length))} failed` : ''}`,
+  );
+
+  if (failures.length > 0) {
+    console.log();
+    for (const f of failures) {
+      console.log(`  ${styles.err('●')} ${styles.bold(f.relativePath)} ${styles.dim('— ' + f.message)}`);
+    }
+    process.exit(1);
+  }
+}

package/src/commands/setup.js

@@ -0,0 +1,256 @@
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import * as styles from '../utils/styles.js';
+import {
+  PLATFORMS,
+  detectExistingCi,
+  detectPlatform,
+  usesBlacksmith,
+} from '../utils/git.js';
+import { templateFor } from '../utils/setup-templates.js';
+
+// Detect the user's CI platform at module load so the top-level `--help`
+// can advertise the right `setup:<platform>` form (e.g. `setup:github` for
+// a GitHub repo). Falls back to the generic `setup:ci`.
+function quickGitRoot() {
+  try {
+    return execSync('git rev-parse --show-toplevel', {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+const _root = quickGitRoot();
+const _detected = _root ? detectPlatform(_root).recommended : null;
+const _hasExistingCi = _root ? detectExistingCi(_root).length > 0 : false;
+const _primaryName = _detected ? `setup:${_detected}` : 'setup:ci';
+const _primaryLabel = _detected ? PLATFORMS[_detected].label : 'a CI workflow';
+
+export const command = _primaryName;
+export const order = 5;
+export const category = 'Linting';
+export const description = `Set up ${_primaryLabel} to lint your docs on every PR`;
+// Skip the hint when existing CI is detected — they've already chosen a platform.
+export const helpHint = _hasExistingCi
+  ? null
+  : `Using something else?\nRun \`${styles.binName()} setup --help\` to see all supported CI platforms.`;
+
+// Hidden aliases cover every other form: bare `setup` (with optional positional),
+// the generic `setup:ci`, and one entry per platform. Whichever form is the
+// primary above is filtered out so it isn't double-registered.
+const ALL_FORMS = [
+  'setup [platform]',
+  'setup:ci',
+  ...Object.keys(PLATFORMS).map((k) => `setup:${k}`),
+];
+export const aliases = ALL_FORMS.filter((a) => a.split(' ')[0] !== _primaryName);
+
+export function args(cmd) {
+  cmd.option('--blacksmith', 'Use Blacksmith runners (GitHub Actions only)');
+  cmd.option('-y, --yes', 'Skip confirmation prompt');
+
+  cmd.addHelpText('after', () => {
+    const bin = styles.binName();
+    const cmdStrs = Object.keys(PLATFORMS).map((k) => `${bin} setup:${k}`);
+    const cmdWidth = Math.max(...cmdStrs.map((s) => s.length));
+    const labelWidth = Math.max(...Object.values(PLATFORMS).map((d) => d.label.length));
+    const rows = Object.entries(PLATFORMS).map(([key, def], i) => {
+      const cmdStr = cmdStrs[i].padEnd(cmdWidth);
+      const label = def.label.padEnd(labelWidth);
+      const marker = key === _detected ? styles.success('●') : ' ';
+      return `  ${marker} ${styles.orange(cmdStr)} ${styles.dim('—')} ${label}  ${styles.dim(def.workflowFile)}`;
+    });
+    const examples = [
+      [`${bin} setup`, '# auto-detect and confirm'],
+      [`${bin} setup:github --blacksmith`, '# GitHub Actions on Blacksmith runners'],
+      [`${bin} setup:gitlab -y`, '# skip the confirmation prompt'],
+    ];
+    const exWidth = Math.max(...examples.map(([c]) => c.length));
+    const exRows = examples.map(([c, note]) => `  ${styles.orange(c.padEnd(exWidth))}  ${styles.dim(note)}`);
+    const detectedLine = _detected
+      ? `  ${styles.dim('Detected:')} ${styles.bold(PLATFORMS[_detected].label)} ${styles.dim('— recommend')} ${styles.orange(`${bin} setup:${_detected}`)}`
+      : `  ${styles.dim('Run')} ${styles.orange(`${bin} setup`)} ${styles.dim('to auto-detect from .git/config + existing CI files.')}`;
+    return [
+      '',
+      `${styles.bold('Auto-detection:')}`,
+      detectedLine,
+      '',
+      `${styles.bold('Platforms:')}`,
+      ...rows,
+      '',
+      `${styles.bold('Examples:')}`,
+      ...exRows,
+      '',
+    ].join('\n');
+  });
+}
+
+export async function run(...callArgs) {
+  // Action signature varies by which form was invoked:
+  //   `setup:github`        → (opts, cmd, ctx)
+  //   `setup [platform]`    → (platformPositional, opts, cmd, ctx)
+  // ctx is always last (added by cli.js bootstrap).
+  const ctx = callArgs.pop();
+  const cmd = callArgs.pop();
+  const opts = callArgs.pop();
+  const positional = callArgs[0];
+
+  // Pull platform from the matched command name, or fall back to the positional.
+  const cmdName = cmd.name();
+  let platformArg = null;
+  if (cmdName.startsWith('setup:') && cmdName !== 'setup:ci') {
+    platformArg = cmdName.slice('setup:'.length);
+  } else if (positional) {
+    platformArg = positional;
+  }
+
+  const { gitRoot } = ctx;
+
+  // 1. Resolve which platform we're setting up.
+  let platform = normalizePlatform(platformArg);
+  let detection = null;
+
+  if (!platform) {
+    detection = detectPlatform(gitRoot);
+    platform = detection.recommended;
+
+    if (!platform) {
+      printDetectionFailure();
+      process.exit(1);
+    }
+  } else if (!PLATFORMS[platform]) {
+    styles.error(`Unknown platform: ${styles.bold(platformArg)}`);
+    styles.info(`Available: ${Object.keys(PLATFORMS).join(', ')}`);
+    process.exit(1);
+  }
+
+  // 2. Validate platform-specific options.
+  if (opts.blacksmith && platform !== 'github') {
+    styles.error('--blacksmith is only valid with GitHub Actions.');
+    process.exit(1);
+  }
+
+  let useBlacksmith = !!opts.blacksmith;
+  if (platform === 'github' && !opts.blacksmith && usesBlacksmith(gitRoot)) {
+    useBlacksmith = true;
+  }
+
+  const def = PLATFORMS[platform];
+  const workflowPath = path.join(gitRoot, def.workflowFile);
+  const isOverwrite = fs.existsSync(workflowPath);
+
+  // 3. Show what will happen.
+  console.log();
+  console.log(`  ${styles.heading(`${def.label} Setup`)}`);
+  console.log();
+
+  if (detection) printDetectionSummary(detection, platform);
+
+  console.log(`  This will create a workflow that runs on every pull request:`);
+  console.log();
+  console.log(`    ${styles.success('✔')} ${styles.bold('Lint docs')} — runs ${styles.orange(`${styles.binName()} lint`)} and posts results as a PR comment`);
+  if (platform === 'github') {
+    console.log(`    ${styles.success('✔')} ${styles.bold('OAS change detection')} — flags modified OpenAPI spec files and suggests syncing`);
+    console.log(`    ${styles.success('✔')} ${styles.bold('Auto-fix base branch')} — redirects PRs from ${styles.orange('main')} to the correct version branch`);
+    if (useBlacksmith) {
+      console.log(`    ${styles.success('✔')} ${styles.bold('Blacksmith runner')} — uses ${styles.orange('blacksmith-2vcpu-ubuntu-2404')} instead of ${styles.orange('ubuntu-latest')}`);
+    }
+  }
+  console.log();
+  console.log(`  ${styles.dim('Creates:')} ${path.relative(gitRoot, workflowPath)}`);
+
+  printPostSetupNotes(platform);
+  console.log();
+
+  // 4. Confirm.
+  if (!opts.yes) {
+    const prompt = isOverwrite
+      ? 'This will overwrite the existing workflow. Continue?'
+      : 'Set up this workflow?';
+    const confirmed = await confirm(prompt);
+    if (!confirmed) {
+      styles.info('Setup cancelled.');
+      return;
+    }
+  }
+
+  // 5. Write.
+  fs.mkdirSync(path.dirname(workflowPath), { recursive: true });
+  fs.writeFileSync(workflowPath, templateFor(platform, { blacksmith: useBlacksmith }));
+
+  console.log();
+  styles.ok(`Created ${def.label} workflow!`);
+  console.log();
+  styles.info('Commit and push this file to start linting PRs automatically.');
+}
+
+function normalizePlatform(input) {
+  if (!input) return null;
+  const key = input.toLowerCase();
+  if (key === 'gh') return 'github';
+  if (key === 'gl') return 'gitlab';
+  if (key === 'bb' || key === 'bitbucket-pipelines') return 'bitbucket';
+  if (key === 'circle' || key === 'circle-ci') return 'circleci';
+  if (key === 'mint') return 'rwx';
+  return key;
+}
+
+function printDetectionSummary(detection, chosen) {
+  const lines = [];
+  if (detection.existing.length > 0) {
+    const labels = detection.existing.map((k) => PLATFORMS[k].label).join(', ');
+    lines.push(`${styles.dim('Detected existing CI:')} ${labels}`);
+  }
+  if (detection.remote) {
+    lines.push(`${styles.dim('Detected git remote:')} ${PLATFORMS[detection.remote].label}`);
+  }
+  lines.push(`${styles.dim('Setting up:')} ${styles.bold(PLATFORMS[chosen].label)}`);
+  for (const l of lines) console.log(`  ${l}`);
+  console.log();
+}
+
+function printDetectionFailure() {
+  console.log();
+  styles.error("Couldn't detect a CI platform for this repo.");
+  console.log();
+  console.log(`  ${styles.dim('No matching git remote and no existing CI config found.')}`);
+  console.log();
+  console.log(`  Specify a platform explicitly:`);
+  for (const [key, def] of Object.entries(PLATFORMS)) {
+    console.log(`    ${styles.orange(`${styles.binName()} setup:${key}`)} ${styles.dim('—')} ${def.label}`);
+  }
+  console.log();
+}
+
+function printPostSetupNotes(platform) {
+  const notes = {
+    gitlab: `  ${styles.dim('Required:')} CI/CD variable ${styles.bold('GITLAB_TOKEN')} with ${styles.bold('api')} scope`,
+    bitbucket: `  ${styles.dim('Required:')} repository variables ${styles.bold('BITBUCKET_USERNAME')} and ${styles.bold('BITBUCKET_TOKEN')} (app password with ${styles.bold('pullrequest:write')})`,
+    circleci: `  ${styles.dim('Required:')} project env var ${styles.bold('CIRCLE_PROJECT_GITHUB_TOKEN')} with PR comment permission`,
+    rwx: `  ${styles.dim('Required:')} vault secret ${styles.bold('GITHUB_TOKEN')} with PR comment permission`,
+  };
+  if (notes[platform]) {
+    console.log();
+    console.log(notes[platform]);
+  }
+}
+
+function confirm(message) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(`${styles.brand('?')} ${message} ${styles.dim('(Y/n)')} `, (answer) => {
+      rl.close();
+      const val = answer.trim().toLowerCase();
+      resolve(val === '' || val === 'y' || val === 'yes');
+    });
+  });
+}

package/src/commands/versions.js

@@ -0,0 +1,81 @@
+import { execSync } from 'node:child_process';
+import * as styles from '../utils/styles.js';
+
+export const command = 'versions';
+export const order = 4;
+export const category = 'Other';
+export const description = 'List all doc versions and their branches';
+
+const VERSION_RE = /^v\d+(\.\d+)*$/;
+const SUB_BRANCH_RE = /^(v\d+(?:\.\d+)*)_(.+)$/;
+
+export function run(_options, _cmd, ctx) {
+  const { gitRoot } = ctx;
+
+  const raw = execSync('git branch -a --format="%(refname:short)"', {
+    cwd: gitRoot,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  }).trim();
+
+  const branches = raw.split('\n').map((b) => b.trim()).filter(Boolean);
+
+  // Strip "origin/" prefix and deduplicate.
+  const seen = new Set();
+  const cleaned = [];
+  for (const b of branches) {
+    const name = b.replace(/^origin\//, '');
+    if (!seen.has(name)) {
+      seen.add(name);
+      cleaned.push(name);
+    }
+  }
+
+  // Group: version branches and their sub-branches.
+  const versions = new Map();
+  const subBranches = [];
+
+  for (const name of cleaned) {
+    if (VERSION_RE.test(name)) {
+      versions.set(name, []);
+    } else {
+      const match = name.match(SUB_BRANCH_RE);
+      if (match) {
+        subBranches.push({ parent: match[1], name: match[2], full: name });
+      }
+    }
+  }
+
+  // Attach sub-branches to their parent version.
+  for (const sub of subBranches) {
+    if (versions.has(sub.parent)) {
+      versions.get(sub.parent).push(sub);
+    }
+  }
+
+  // Sort versions by semver-ish ordering (descending).
+  const sorted = [...versions.entries()].sort((a, b) => {
+    const aParts = a[0].slice(1).split('.').map(Number);
+    const bParts = b[0].slice(1).split('.').map(Number);
+    for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+      const diff = (bParts[i] || 0) - (aParts[i] || 0);
+      if (diff !== 0) return diff;
+    }
+    return 0;
+  });
+
+  console.log();
+  console.log(`  ${styles.logo()}  ${styles.dim('versions')}`);
+  console.log();
+
+  for (const [version, subs] of sorted) {
+    console.log(`  ${styles.bold(version)}`);
+    for (let i = 0; i < subs.length; i++) {
+      const isLast = i === subs.length - 1;
+      const connector = isLast ? '└─' : '├─';
+      console.log(`  ${styles.dim(connector)} ${styles.dim(version + '_')}${subs[i].name} ${styles.dim('(branch)')}`);
+    }
+  }
+
+  console.log();
+}

package/src/dev/.next/app-build-manifest.json

@@ -0,0 +1,20 @@
+{
+  "pages": {
+    "/layout": [
+      "static/chunks/webpack.js",
+      "static/chunks/main-app.js",
+      "static/css/app/layout.css",
+      "static/chunks/app/layout.js"
+    ],
+    "/[...slug]/loading": [
+      "static/chunks/webpack.js",
+      "static/chunks/main-app.js",
+      "static/chunks/app/[...slug]/loading.js"
+    ],
+    "/[...slug]/page": [
+      "static/chunks/webpack.js",
+      "static/chunks/main-app.js",
+      "static/chunks/app/[...slug]/page.js"
+    ]
+  }
+}

package/src/dev/.next/build-manifest.json

@@ -0,0 +1,31 @@
+{
+  "polyfillFiles": [
+    "static/chunks/polyfills.js"
+  ],
+  "devFiles": [
+    "static/chunks/react-refresh.js"
+  ],
+  "ampDevFiles": [],
+  "lowPriorityFiles": [
+    "static/development/_buildManifest.js",
+    "static/development/_ssgManifest.js"
+  ],
+  "rootMainFiles": [
+    "static/chunks/webpack.js",
+    "static/chunks/main-app.js"
+  ],
+  "rootMainFilesTree": {},
+  "pages": {
+    "/_app": [
+      "static/chunks/webpack.js",
+      "static/chunks/main.js",
+      "static/chunks/pages/_app.js"
+    ],
+    "/_error": [
+      "static/chunks/webpack.js",
+      "static/chunks/main.js",
+      "static/chunks/pages/_error.js"
+    ]
+  },
+  "ampFirstPages": []
+}

package/src/dev/.next/cache/.rscinfo

@@ -0,0 +1 @@
+{"encryption.key":"3SIKRvTdjH2KvDXOUMwtVkaVmj4v5oCsYq33R2HYXtM=","encryption.expire_at":1772814750891}

package/src/dev/.next/cache/next-devtools-config.json

@@ -0,0 +1 @@
+{}

package/src/dev/.next/package.json

@@ -0,0 +1 @@
+{"type": "commonjs"}

package/src/dev/.next/prerender-manifest.json

@@ -0,0 +1,11 @@
+{
+  "version": 4,
+  "routes": {},
+  "dynamicRoutes": {},
+  "notFoundRoutes": [],
+  "preview": {
+    "previewModeId": "b628b03ee18bb42bb63fcc51ca49946f",
+    "previewModeSigningKey": "f82f45cc5833fe189f9cc960b8dd1be2c6c51a3c05cf345f3497ced03b8c7b0d",
+    "previewModeEncryptionKey": "ab192619b9dd28eb198eda117db9c62df8ca0dba79469500b34cdcdf2b290da3"
+  }
+}