@readme/cli 0.0.26

package/src/utils/reporter.js

@@ -0,0 +1,319 @@
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import ora from "ora";
+import * as styles from "./styles.js";
+import { hasClaude } from "./claude.js";
+import { hasGithubRemote, hasGithubWorkflow, getWorkflowVersion, WORKFLOW_VERSION, detectPlatform, hasReadmeWorkflow, PLATFORMS } from "./git.js";
+import { getRandomTip } from "./tips.js";
+
+const require = createRequire(import.meta.url);
+
+const isRunningInClaude = !!process.env.CLAUDECODE;
+
+const CATEGORY_LABELS = {
+  custom_blocks: "custom blocks",
+  docs: "docs",
+  reference: "reference",
+  custom_pages: "custom pages",
+  recipes: "recipes",
+};
+
+function categorize(files) {
+  const counts = new Map();
+  for (const file of files) {
+    const dir = file.split("/")[0];
+    const label = CATEGORY_LABELS[dir] || dir;
+    counts.set(label, (counts.get(label) || 0) + 1);
+  }
+  return [...counts.entries()];
+}
+
+function splitResults(results) {
+  const errors = results.filter((r) => r.severity !== "warning");
+  const warnings = results.filter((r) => r.severity === "warning");
+  return { errors, warnings };
+}
+
+/**
+ * Style a result message for human display.
+ * Title (before first ":") is colored, rest is normal with bold quoted values.
+ */
+function styleMessage(message, color) {
+  // Strip "(fixed)" suffix — handled separately via the icon.
+  const isFixed = message.endsWith("(fixed)");
+  const raw = isFixed ? message.slice(0, -"(fixed)".length).trimEnd() : message;
+
+  const colonIdx = raw.indexOf(":");
+  let styled;
+
+  if (colonIdx !== -1) {
+    const title = raw.slice(0, colonIdx);
+    const detail = raw
+      .slice(colonIdx + 1)
+      .replace(/"([^"]+)"/g, (_, val) => styles.bold(`"${val}"`));
+    styled = `${color(title)}:${detail}`;
+  } else {
+    // No colon — highlight quoted values, keep rest normal.
+    styled = raw.replace(/"([^"]+)"/g, (_, val) => styles.bold(`"${val}"`));
+  }
+
+  return styled;
+}
+
+function summaryLine(errorCount, warningCount) {
+  const parts = [];
+  if (errorCount > 0)
+    parts.push(`${errorCount} ${errorCount === 1 ? "error" : "errors"}`);
+  if (warningCount > 0)
+    parts.push(
+      `${warningCount} ${warningCount === 1 ? "warning" : "warnings"}`,
+    );
+  return parts.join(" and ");
+}
+
+/**
+ * Human-readable reporter with an animated spinner.
+ */
+export function createHumanReporter() {
+  const spinner = ora({ text: "Running linting...", color: "blue" }).start();
+
+  return {
+    onFile(relativePath) {
+      spinner.suffixText = styles.dim(relativePath);
+    },
+
+    pause() {
+      spinner.stop();
+    },
+
+    finish(total, results, files, { fix, gitRoot } = {}) {
+      spinner.suffixText = "";
+
+      const { errors, warnings } = splitResults(results);
+      const categories = categorize(files);
+      const breakdown = categories
+        .map(([label, count]) => `${count} ${label}`)
+        .join(styles.dim(" · "));
+
+      if (errors.length === 0 && warnings.length === 0) {
+        spinner.succeed(`${total} files checked — all good!`);
+        console.log(`  ${styles.dim(breakdown)}`);
+        return;
+      }
+
+      if (errors.length > 0) {
+        spinner.fail(
+          `${summaryLine(errors.length, warnings.length)} in ${total} files`,
+        );
+      } else {
+        spinner.warn(`${summaryLine(0, warnings.length)} in ${total} files`);
+      }
+      console.log(`  ${styles.dim(breakdown)}`);
+      console.log();
+
+      // Group all results by file
+      const grouped = new Map();
+      for (const r of [...errors, ...warnings]) {
+        if (!grouped.has(r.file)) grouped.set(r.file, []);
+        grouped.get(r.file).push(r);
+      }
+
+      for (const [file, fileResults] of grouped) {
+        console.log(`  ${styles.bold(file)}`);
+        for (const r of fileResults) {
+          const baseColor = r.severity === "warning" ? styles.warn : styles.err;
+          const isFixed = r.message.endsWith("(fixed)");
+          const color = isFixed ? styles.success : baseColor;
+          const styled = styleMessage(r.message, color);
+          const icon = isFixed ? styles.success("✔") : baseColor("●");
+          console.log(`    ${icon} ${styled}`);
+        }
+        console.log();
+      }
+
+      // Tips section.
+      const fixable = !fix
+        ? results.filter((r) => r.fixable && !r.message.endsWith("(fixed)"))
+        : [];
+      const unfixed = results.filter((r) => !r.message.endsWith("(fixed)"));
+      const showTips =
+        fixable.length > 0 || (unfixed.length > 0 && !isRunningInClaude);
+
+      if (showTips) {
+        console.log(`  ${styles.dim("─".repeat(40))}`);
+        console.log();
+      }
+
+      if (fixable.length > 0) {
+        console.log(
+          `  ${styles.dim("Run")} ${styles.binName()} lint --fix ${styles.dim("to automatically fix some of these.")}`,
+        );
+        console.log();
+      }
+
+      if (unfixed.length > 0 && !isRunningInClaude) {
+        const hasWorkflow = gitRoot ? hasGithubWorkflow(gitRoot) : true;
+        const workflowVersion = gitRoot ? getWorkflowVersion(gitRoot) : null;
+        const detection = gitRoot ? detectPlatform(gitRoot) : { recommended: null };
+        const detectedPlatform = detection.recommended;
+        const hasCiWorkflow = detectedPlatform && gitRoot
+          ? hasReadmeWorkflow(gitRoot, detectedPlatform)
+          : true;
+        const tip = getRandomTip({
+          isRunningInClaude,
+          hasClaude: hasClaude(),
+          hasGithubRemote: hasGithubRemote(),
+          hasGithubWorkflow: hasWorkflow,
+          workflowOutdated: hasWorkflow && workflowVersion !== null && workflowVersion < WORKFLOW_VERSION,
+          detectedPlatform,
+          detectedPlatformLabel: detectedPlatform ? PLATFORMS[detectedPlatform].label : null,
+          hasCiWorkflow,
+        });
+        if (tip) tip.render();
+      }
+
+      // When running inside Claude, output instructions and structured issue list.
+      if (isRunningInClaude && unfixed.length > 0) {
+        const cliRoot = path.join(
+          path.dirname(new URL(import.meta.url).pathname),
+          "../..",
+        );
+
+        const gitFormatDir = path.dirname(require.resolve('@readmeio/git-format/package.json'));
+        const claudeMdPath = path.join(gitFormatDir, "CLAUDE.md");
+        const toolsMdPath = path.join(cliRoot, "vendor/TOOLS.md");
+        const schemaPath = path.join(gitFormatDir, "frontmatter.schema.json");
+
+        console.log("\n<claude-instructions>");
+
+        if (fs.existsSync(toolsMdPath)) {
+          console.log(fs.readFileSync(toolsMdPath, "utf-8"));
+        }
+
+        if (fs.existsSync(claudeMdPath)) {
+          console.log(fs.readFileSync(claudeMdPath, "utf-8"));
+        }
+
+        if (fs.existsSync(schemaPath)) {
+          console.log("\n## Frontmatter JSON Schema\n");
+          console.log("```json");
+          console.log(fs.readFileSync(schemaPath, "utf-8"));
+          console.log("```");
+        }
+
+        console.log("</claude-instructions>\n");
+        console.log("<issues>");
+        for (const r of unfixed) {
+          console.log(`- [${r.severity}] ${r.file}: ${r.message}`);
+        }
+        console.log("</issues>");
+      }
+    },
+  };
+}
+
+/**
+ * GitHub reporter — outputs a PR comment body as markdown.
+ */
+export function createGithubReporter() {
+  return {
+    onFile() {},
+    pause() {},
+
+    finish(total, results, _files, { gitRoot } = {}) {
+      const { errors, warnings } = splitResults(results);
+      const all = [...errors, ...warnings];
+
+      // Build file links using GitHub Actions env vars
+      const serverUrl = process.env.GITHUB_SERVER_URL || "https://github.com";
+      const repo = process.env.GITHUB_REPOSITORY || "";
+      const sha = process.env.GITHUB_SHA || "";
+      const canLink = repo && sha;
+
+      function fileLink(filePath) {
+        const name = filePath.split("/").pop();
+        if (canLink) {
+          const encoded = filePath.split("/").map(encodeURIComponent).join("/");
+          return `[\`${name}\`](${serverUrl}/${repo}/blob/${sha}/${encoded})`;
+        }
+        return `\`${name}\``;
+      }
+
+      let body = "<!-- readme-lint-results -->\n";
+      body += "## ReadMe Docs Lint\n\n";
+
+      if (all.length === 0) {
+        body += "> **All checks passed!** No lint issues found.\n";
+      } else {
+        body += "| File | Message |\n";
+        body += "|------|--------|\n";
+        for (const r of all) {
+          const isError = r.severity !== "warning";
+          const label = isError ? "\u{1F534} **Error:**" : "\u{1F7E1} **Warning:**";
+          body += `| ${fileLink(r.file)} | ${label} ${r.message} |\n`;
+        }
+        body += "\n";
+        body += "> \u{1F4A1} **Tip:** Run `npx @readme/cli lint --fix` locally to automatically fix some of these issues.\n\n";
+      }
+
+      // OAS change detection
+      const baseSha = process.env.GITHUB_BASE_SHA;
+      if (baseSha && gitRoot) {
+        try {
+          const changed = execSync(
+            `git diff --name-only ${baseSha}..HEAD -- 'reference/*.json' 'reference/*.yaml' 'reference/*.yml'`,
+            { cwd: gitRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] },
+          ).trim();
+
+          if (changed) {
+            const files = changed.split("\n");
+            body += "### OAS Changes Detected\n\n";
+            body += "The following OpenAPI spec files were changed in this PR:\n\n";
+            for (const f of files) {
+              body += `- ${fileLink(f)}\n`;
+            }
+            body += "\nRun `npx @readme/cli oas:sync` to sync these changes to ReadMe.\n\n";
+          }
+        } catch {
+          // git diff failed — skip OAS section silently
+        }
+      }
+
+      body += "---\n";
+      body += "\u{1F989} Powered by [ReadMe](https://readme.com)\n";
+
+      console.log(body);
+    },
+  };
+}
+
+/**
+ * JSON reporter for machine consumption.
+ */
+export function createJsonReporter() {
+  return {
+    onFile() {},
+    pause() {},
+
+    finish(total, results, _files) {
+      const { errors, warnings } = splitResults(results);
+      const output = {
+        ok: errors.length === 0,
+        total,
+        errors: errors.map(({ file, rule, message }) => ({
+          file,
+          rule,
+          message,
+        })),
+        warnings: warnings.map(({ file, rule, message }) => ({
+          file,
+          rule,
+          message,
+        })),
+      };
+      console.log(JSON.stringify(output));
+    },
+  };
+}

package/src/utils/setup-templates.js

@@ -0,0 +1,323 @@
+import { WORKFLOW_VERSION } from './git.js';
+
+const VERSION_HEADER = `# readme-lint v${WORKFLOW_VERSION}`;
+
+const GITHUB_DEFAULT_RUNNER = 'ubuntu-latest';
+const GITHUB_BLACKSMITH_RUNNER = 'blacksmith-2vcpu-ubuntu-2404';
+
+export function githubWorkflow({ blacksmith = false } = {}) {
+  const runner = blacksmith ? GITHUB_BLACKSMITH_RUNNER : GITHUB_DEFAULT_RUNNER;
+  return `${VERSION_HEADER}
+name: ReadMe Docs Lint
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+  packages: read
+
+jobs:
+  lint:
+    name: Lint docs
+    runs-on: ${runner}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Fix PR base branch
+        id: fix-base
+        if: github.event.pull_request.base.ref == 'main' || github.event.pull_request.base.ref == 'master'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const head = context.payload.pull_request.head.ref;
+            const match = head.match(/^(v\\d+(?:\\.\\d+)*)/);
+            if (!match) return;
+
+            const versionBranch = match[1];
+
+            try {
+              await github.rest.repos.getBranch({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                branch: versionBranch,
+              });
+            } catch {
+              return;
+            }
+
+            await github.rest.pulls.update({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.issue.number,
+              base: versionBranch,
+            });
+
+            core.setOutput('changed', 'true');
+            core.setOutput('new_base', versionBranch);
+            core.setOutput('old_base', context.payload.pull_request.base.ref);
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://npm.pkg.github.com
+
+      - name: Lint docs
+        id: lint
+        continue-on-error: true
+        env:
+          NODE_AUTH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+          GITHUB_BASE_SHA: \${{ github.event.pull_request.base.sha }}
+        run: npx -y @readme/cli --no-check lint --github > comment.md
+
+      - name: Comment on PR
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const marker = '<!-- readme-lint-results -->';
+            let body = '';
+            try { body = fs.readFileSync('comment.md', 'utf-8'); } catch {}
+            if (!body.includes(marker)) return;
+
+            const baseChanged = '\${{ steps.fix-base.outputs.changed }}' === 'true';
+            if (baseChanged) {
+              const oldBase = '\${{ steps.fix-base.outputs.old_base }}';
+              const newBase = '\${{ steps.fix-base.outputs.new_base }}';
+              body = body.replace('---', \`> **Base branch updated:** This PR was targeting \\\`\${oldBase}\\\` but has been updated to target \\\`\${newBase}\\\`.\\n\\n---\`);
+            }
+
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            const existing = comments.find(c => c.body.includes(marker));
+
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }
+
+
+      - name: Fail if lint errors
+        if: steps.lint.outcome == 'failure'
+        run: exit 1
+`;
+}
+
+export function gitlabWorkflow() {
+  return `${VERSION_HEADER}
+# Lints ReadMe docs on every merge request and posts results as an MR note.
+# Requires a CI/CD variable named GITLAB_TOKEN with api scope (Settings → CI/CD → Variables)
+# so the job can post comments back to the merge request.
+
+readme-lint:
+  stage: test
+  image: node:20
+  rules:
+    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
+  variables:
+    GIT_DEPTH: 0
+  script:
+    - git fetch origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+    - export GITHUB_BASE_SHA="$(git rev-parse origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME)"
+    - npx -y @readme/cli --no-check lint --github > comment.md || echo "LINT_FAILED=1" >> lint.env
+    - |
+      if [ -s comment.md ] && grep -q '<!-- readme-lint-results -->' comment.md; then
+        BODY=$(cat comment.md)
+        AUTH_HEADER="PRIVATE-TOKEN: $GITLAB_TOKEN"
+        API="$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"
+        EXISTING=$(curl -s -H "$AUTH_HEADER" "$API" | grep -o '"id":[0-9]*,"type":[^,]*,"body":"<!-- readme-lint-results -->' | head -1 | grep -o '"id":[0-9]*' | cut -d: -f2)
+        if [ -n "$EXISTING" ]; then
+          curl -s -X PUT -H "$AUTH_HEADER" --data-urlencode "body=$BODY" "$API/$EXISTING" > /dev/null
+        else
+          curl -s -X POST -H "$AUTH_HEADER" --data-urlencode "body=$BODY" "$API" > /dev/null
+        fi
+      fi
+    - if [ -f lint.env ]; then exit 1; fi
+  artifacts:
+    when: always
+    paths:
+      - comment.md
+`;
+}
+
+export function bitbucketWorkflow() {
+  return `${VERSION_HEADER}
+# Lints ReadMe docs on every pull request and posts results as a PR comment.
+# Requires a repository variable named BITBUCKET_TOKEN (an app password with
+# pullrequest:write scope) so the job can post comments back to the PR.
+
+image: node:20
+
+pipelines:
+  pull-requests:
+    '**':
+      - step:
+          name: Lint ReadMe docs
+          clone:
+            depth: full
+          script:
+            - export GITHUB_BASE_SHA="$(git rev-parse origin/$BITBUCKET_PR_DESTINATION_BRANCH)"
+            - LINT_RC=0
+            - npx -y @readme/cli --no-check lint --github > comment.md || LINT_RC=$?
+            - |
+              if [ -s comment.md ] && grep -q '<!-- readme-lint-results -->' comment.md; then
+                BODY=$(cat comment.md)
+                API="https://api.bitbucket.org/2.0/repositories/$BITBUCKET_WORKSPACE/$BITBUCKET_REPO_SLUG/pullrequests/$BITBUCKET_PR_ID/comments"
+                AUTH="-u $BITBUCKET_USERNAME:$BITBUCKET_TOKEN"
+                EXISTING=$(curl -s $AUTH "$API?pagelen=100" | grep -o '"id":[0-9]*[^}]*<!-- readme-lint-results -->' | head -1 | grep -o '"id":[0-9]*' | cut -d: -f2)
+                JSON=$(node -e "console.log(JSON.stringify({content:{raw:require('fs').readFileSync('comment.md','utf-8')}}))")
+                if [ -n "$EXISTING" ]; then
+                  curl -s -X PUT $AUTH -H 'Content-Type: application/json' -d "$JSON" "$API/$EXISTING" > /dev/null
+                else
+                  curl -s -X POST $AUTH -H 'Content-Type: application/json' -d "$JSON" "$API" > /dev/null
+                fi
+              fi
+            - exit $LINT_RC
+          artifacts:
+            - comment.md
+`;
+}
+
+export function circleciWorkflow() {
+  return `${VERSION_HEADER}
+# Lints ReadMe docs on every PR and posts results as a PR comment.
+# Requires CIRCLE_PROJECT_GITHUB_TOKEN (or your VCS-equivalent) as an env var
+# in the project settings, with permission to comment on pull requests.
+
+version: 2.1
+
+jobs:
+  readme-lint:
+    docker:
+      - image: cimg/node:20.11
+    steps:
+      - checkout
+      - run:
+          name: Lint ReadMe docs
+          command: |
+            BASE_BRANCH="\${CIRCLE_PR_BASE_BRANCH:-main}"
+            git fetch origin "$BASE_BRANCH" || true
+            export GITHUB_BASE_SHA="$(git rev-parse origin/$BASE_BRANCH 2>/dev/null || echo '')"
+            set +e
+            npx -y @readme/cli --no-check lint --github > comment.md
+            LINT_RC=$?
+            set -e
+            if [ -n "$CIRCLE_PULL_REQUEST" ] && grep -q '<!-- readme-lint-results -->' comment.md; then
+              PR_NUM=$(echo "$CIRCLE_PULL_REQUEST" | awk -F/ '{print $NF}')
+              REPO="$CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME"
+              API="https://api.github.com/repos/$REPO/issues/$PR_NUM/comments"
+              AUTH="Authorization: token $CIRCLE_PROJECT_GITHUB_TOKEN"
+              EXISTING=$(curl -s -H "$AUTH" "$API?per_page=100" | grep -B1 '<!-- readme-lint-results -->' | grep -o '"id": [0-9]*' | head -1 | awk '{print $2}')
+              JSON=$(node -e "console.log(JSON.stringify({body: require('fs').readFileSync('comment.md','utf-8')}))")
+              if [ -n "$EXISTING" ]; then
+                curl -s -X PATCH -H "$AUTH" -H 'Content-Type: application/json' -d "$JSON" "https://api.github.com/repos/$REPO/issues/comments/$EXISTING" > /dev/null
+              else
+                curl -s -X POST -H "$AUTH" -H 'Content-Type: application/json' -d "$JSON" "$API" > /dev/null
+              fi
+            fi
+            exit $LINT_RC
+          environment:
+            NODE_OPTIONS: --max-old-space-size=4096
+
+workflows:
+  readme:
+    jobs:
+      - readme-lint:
+          filters:
+            branches:
+              ignore:
+                - main
+                - master
+`;
+}
+
+export function rwxWorkflow() {
+  return `${VERSION_HEADER}
+# Lints ReadMe docs on every PR and posts results as a PR comment.
+# Requires a vault secret named GITHUB_TOKEN with permission to comment on PRs.
+
+on:
+  github:
+    pull_request:
+      init:
+        commit-sha: \${{ event.pull_request.head.sha }}
+        pr-number: \${{ event.pull_request.number }}
+        repo: \${{ event.repository.full_name }}
+        base-sha: \${{ event.pull_request.base.sha }}
+
+tasks:
+  - key: code
+    call: mint/git-clone 1.6.6
+    with:
+      repository: https://github.com/\${{ init.repo }}.git
+      ref: \${{ init.commit-sha }}
+
+  - key: node
+    call: mint/install-node 1.1.5
+    with:
+      node-version: '20'
+
+  - key: lint
+    use: [code, node]
+    run: |
+      set +e
+      GITHUB_BASE_SHA="\${{ init.base-sha }}" npx -y @readme/cli --no-check lint --github > comment.md
+      echo $? > lint.rc
+    filter:
+      - comment.md
+      - lint.rc
+
+  - key: comment
+    use: lint
+    env:
+      GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+      REPO: \${{ init.repo }}
+      PR: \${{ init.pr-number }}
+    run: |
+      if ! grep -q '<!-- readme-lint-results -->' comment.md; then exit 0; fi
+      API="https://api.github.com/repos/$REPO/issues/$PR/comments"
+      AUTH="Authorization: token $GITHUB_TOKEN"
+      EXISTING=$(curl -s -H "$AUTH" "$API?per_page=100" | grep -B1 '<!-- readme-lint-results -->' | grep -o '"id": [0-9]*' | head -1 | awk '{print $2}')
+      JSON=$(node -e "console.log(JSON.stringify({body: require('fs').readFileSync('comment.md','utf-8')}))")
+      if [ -n "$EXISTING" ]; then
+        curl -s -X PATCH -H "$AUTH" -H 'Content-Type: application/json' -d "$JSON" "https://api.github.com/repos/$REPO/issues/comments/$EXISTING" > /dev/null
+      else
+        curl -s -X POST -H "$AUTH" -H 'Content-Type: application/json' -d "$JSON" "$API" > /dev/null
+      fi
+
+  - key: report
+    use: lint
+    run: exit "$(cat lint.rc)"
+`;
+}
+
+export function templateFor(platform, opts = {}) {
+  switch (platform) {
+    case 'github':    return githubWorkflow(opts);
+    case 'gitlab':    return gitlabWorkflow();
+    case 'bitbucket': return bitbucketWorkflow();
+    case 'circleci':  return circleciWorkflow();
+    case 'rwx':       return rwxWorkflow();
+    default: throw new Error(`Unknown platform: ${platform}`);
+  }
+}

package/src/utils/styles.js

@@ -0,0 +1,50 @@
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import chalk from 'chalk';
+
+/** Returns the CLI name depending on how it was invoked (e.g. "readme", "readme_", or "npx @readme/cli"). */
+export function binName() {
+  const base = path.basename(process.argv[1] || 'readme');
+
+  // When run via npx, npm sets npm_command=exec. Use our own package.json name
+  // (not npm_package_name, which refers to the CWD project, not the CLI).
+  if (process.env.npm_command === 'exec') {
+    const require = createRequire(import.meta.url);
+    const pkg = require('../../package.json');
+    return `npx ${pkg.name}`;
+  }
+
+  return base;
+}
+
+export const brand = chalk.hex('#018ef5'); // ReadMe blue
+export const success = chalk.green;
+export const warn = chalk.yellow;
+export const err = chalk.red;
+export const orange = chalk.hex('#63D2FF');
+export const dim = chalk.dim;
+export const bold = chalk.bold;
+
+export function logo() {
+  return brand('🦉 readme');
+}
+
+export function heading(text) {
+  return bold(brand(text));
+}
+
+export function info(message) {
+  console.log(`${dim('›')} ${message}`);
+}
+
+export function error(message) {
+  console.error(`${err('✘')} ${message}`);
+}
+
+export function ok(message) {
+  console.log(`${success('✔')} ${message}`);
+}
+
+export function warning(message) {
+  console.log(`${warn('⚠')} ${message}`);
+}