template-git-repo 0.1.0

package/src/badges.js

@@ -0,0 +1,353 @@
+/**
+ * The badge catalog: the README badge row, as data.
+ *
+ * Modeled on the header of OpenSourceAGI/qwksearch-research-agent, which is
+ * where this set was worked out. Each entry knows three things a hand-written
+ * `<img>` tag does not:
+ *
+ *   needs   the context it cannot render without (an npm package name, a
+ *           Discord server id, a DOI). A badge whose inputs are missing is
+ *           left out instead of shipping a README with a broken image.
+ *   setup   what a human has to do outside this repo to make it real, which is
+ *           the part every badge README omits. `docs/BADGES.md` is generated
+ *           from these strings, so the docs cannot drift from the catalog.
+ *   group   which line of the badge block it belongs on. Twenty badges in one
+ *           run is a wall; four rows of five reads.
+ *
+ * Adding a badge means adding an entry here — nothing else in the package
+ * needs to know about it.
+ */
+
+/** Row order in the rendered block. */
+export const GROUPS = ['identity', 'quality', 'community', 'stack'];
+
+/** @typedef {Record<string, string | undefined>} BadgeContext */
+
+/**
+ * `img.shields.io/badge/` takes its label, color and logo positionally, and
+ * every literal `-` in a label has to be doubled. Getting that wrong produces a
+ * badge that renders but says the wrong thing.
+ *
+ * @param {string} label
+ * @param {string} color
+ * @param {Record<string, string>} [params]
+ * @returns {string}
+ */
+export function shieldsBadge(label, color, params = {}) {
+  const encoded = encodeURIComponent(label.replaceAll('-', '--'));
+  const query = new URLSearchParams(params).toString();
+  return `https://img.shields.io/badge/${encoded}-${color}${query ? `?${query}` : ''}`;
+}
+
+/** @type {ReadonlyArray<{ id: string, title: string, group: string, needs: string[], alt: string, href: (c: BadgeContext) => string, img: (c: BadgeContext) => string, setup: string, height?: string }>} */
+export const BADGES = [
+  {
+    id: 'doi',
+    title: 'Zenodo DOI',
+    group: 'identity',
+    needs: ['doi'],
+    alt: 'DOI',
+    href: (c) => `https://doi.org/${c.doi}`,
+    img: (c) => `https://zenodo.org/badge/DOI/${c.doi}.svg`,
+    setup:
+      'Sign in to zenodo.org with GitHub, flip this repository on under Account → GitHub, then publish a GitHub Release. Zenodo archives the release and mints a DOI. Use the *concept* DOI (the one that always resolves to the newest version), not the per-release DOI.',
+  },
+  {
+    id: 'deepwiki',
+    title: 'Ask DeepWiki',
+    group: 'identity',
+    needs: [],
+    alt: 'Ask DeepWiki',
+    href: (c) => `https://deepwiki.com/${c.repoSlug}`,
+    img: () => 'https://deepwiki.com/badge.svg',
+    setup:
+      'Nothing to configure for a public repo — visit deepwiki.com/<owner>/<repo> once to trigger the first index. Private repos need the DeepWiki GitHub App installed.',
+  },
+  {
+    id: 'docs',
+    title: 'Documentation',
+    group: 'identity',
+    needs: ['docsUrl'],
+    alt: 'Documentation',
+    href: (c) => c.docsUrl,
+    img: () => shieldsBadge('Docs', 'blue', { logo: 'ReadTheDocs', logoColor: 'white' }),
+    setup:
+      'Point this at wherever your docs are actually hosted. This is a static shields.io badge — it says "Docs" whether or not the link works, so it is on you to keep the URL alive.',
+  },
+  {
+    id: 'api',
+    title: 'API reference',
+    group: 'identity',
+    needs: ['apiUrl'],
+    alt: 'API',
+    href: (c) => c.apiUrl,
+    img: () => shieldsBadge('API', 'blue', { logo: 'fastapi', logoColor: 'white' }),
+    setup: 'Point this at your OpenAPI / Swagger page. Static badge, same caveat as Docs.',
+  },
+  {
+    id: 'youtube',
+    title: 'YouTube demo',
+    group: 'identity',
+    needs: ['youtubeUrl'],
+    alt: 'YouTube',
+    href: (c) => c.youtubeUrl,
+    img: () => shieldsBadge('YouTube', 'red', { style: 'for-the-badge', logo: 'youtube', logoColor: 'white' }),
+    setup: 'A demo video does more for a README than three paragraphs. Any YouTube URL works.',
+    height: '20px',
+  },
+  {
+    id: 'deploy-cloudflare',
+    title: 'Deploy to Cloudflare Workers',
+    group: 'identity',
+    needs: ['cloudflareDeploy'],
+    alt: 'Deploy to Cloudflare Workers',
+    href: (c) => `https://deploy.workers.cloudflare.com/?url=https://github.com/${c.repoSlug}`,
+    img: () => 'https://deploy.workers.cloudflare.com/button',
+    setup:
+      'The repo must contain a wrangler.toml (or wrangler.jsonc) at the path the button clones. Cloudflare forks the repo into the visitor\'s account and runs the build, so anything the build needs must come from `[vars]` or be prompted for — a build that requires a secret fails for every visitor.',
+    height: '24px',
+  },
+  {
+    id: 'stars',
+    title: 'GitHub stars',
+    group: 'community',
+    needs: [],
+    alt: 'GitHub Stars',
+    href: (c) => `https://github.com/${c.repoSlug}/stargazers`,
+    img: (c) => `https://img.shields.io/github/stars/${c.repoSlug}`,
+    setup: 'Nothing to configure. Public repos only — shields.io cannot read a private repo.',
+  },
+  {
+    id: 'npm-downloads',
+    title: 'npm monthly downloads',
+    group: 'quality',
+    needs: ['npmPackage'],
+    alt: 'NPM Monthly Downloads',
+    href: (c) => `https://www.npmjs.com/package/${c.npmPackage}`,
+    img: (c) => `https://img.shields.io/npm/dm/${c.npmPackage}.svg`,
+    setup:
+      'Requires at least one published version. In a monorepo pick the package you want to advertise — the badge counts one package, not the workspace.',
+  },
+  {
+    id: 'npm-version',
+    title: 'npm version',
+    group: 'quality',
+    needs: ['npmPackage'],
+    alt: 'npm version',
+    href: (c) => `https://www.npmjs.com/package/${c.npmPackage}`,
+    img: (c) => `https://img.shields.io/npm/v/${c.npmPackage}.svg`,
+    setup: 'Shows the `latest` dist-tag. Publishing under a different tag will not move it.',
+  },
+  {
+    id: 'codecov',
+    title: 'Code coverage',
+    group: 'quality',
+    needs: [],
+    alt: 'Coverage',
+    href: (c) => `https://codecov.io/gh/${c.repoSlug}`,
+    img: (c) => `https://codecov.io/gh/${c.repoSlug}/graph/badge.svg`,
+    setup:
+      'Add the repo at codecov.io, copy its upload token into a CODECOV_TOKEN repository secret, and make sure a workflow uploads `coverage/lcov.info` (tests.yml does). Until the first successful upload the badge reads "unknown", which looks identical to a broken badge — check the Codecov dashboard, not the badge, when debugging.',
+  },
+  {
+    id: 'workflow',
+    title: 'CI status',
+    group: 'quality',
+    needs: ['workflowFile'],
+    alt: 'CI status',
+    href: (c) => `https://github.com/${c.repoSlug}/actions/workflows/${c.workflowFile}`,
+    img: (c) =>
+      `https://github.com/${c.repoSlug}/actions/workflows/${c.workflowFile}/badge.svg?branch=${c.defaultBranch}`,
+    setup:
+      'The filename must match the workflow file exactly, and `?branch=` must name your default branch — without it the badge shows the most recent run on *any* branch, so a failing feature branch reads as a broken main.',
+  },
+  {
+    id: 'test-report',
+    title: 'Hosted test report',
+    group: 'quality',
+    needs: ['testReportUrl'],
+    alt: 'Test Report',
+    href: (c) => c.testReportUrl,
+    img: () => shieldsBadge('Test Report', 'brightgreen', { logo: 'vitest', logoColor: 'white' }),
+    setup:
+      'Backed by `.github/workflows/deploy-test-reports.yml`, which publishes the Vitest HTML reporter output to Cloudflare Workers on every push to the default branch. Needs CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID secrets.',
+  },
+  {
+    id: 'uptime',
+    title: 'Uptime',
+    group: 'quality',
+    needs: ['uptimeUrl'],
+    alt: 'Uptime Status',
+    href: (c) => c.uptimeUrl,
+    img: () => shieldsBadge('Uptime-Status', 'brightgreen', { logo: 'uptimerobot', logoColor: 'white' }),
+    setup:
+      'Create a monitor at uptimerobot.com, then a public status page, and link the status page here. This is a static badge — it says "brightgreen" even while you are down. For a live one use the UptimeRobot shields endpoint with a read-only API key.',
+  },
+  {
+    id: 'commit-activity',
+    title: 'Commit activity',
+    group: 'community',
+    needs: [],
+    alt: 'Commit activity',
+    href: (c) => `https://github.com/${c.repoSlug}/graphs/contributors`,
+    img: (c) => `https://img.shields.io/github/commit-activity/m/${c.repoSlug}`,
+    setup: 'Nothing to configure. Commits per month — a quiet month reads as an abandoned project, which is worth knowing before you add it.',
+  },
+  {
+    id: 'last-commit',
+    title: 'Last commit',
+    group: 'community',
+    needs: [],
+    alt: 'GitHub last commit',
+    href: (c) => `https://github.com/${c.repoSlug}/commits/${c.defaultBranch}/`,
+    img: (c) => `https://img.shields.io/github/last-commit/${c.repoSlug}.svg`,
+    setup: 'Nothing to configure. Same caveat as commit activity.',
+  },
+  {
+    id: 'discord',
+    title: 'Discord',
+    group: 'community',
+    needs: ['discordId', 'discordInvite'],
+    alt: 'Join Discord',
+    href: (c) => c.discordInvite,
+    img: (c) =>
+      `https://img.shields.io/discord/${c.discordId}.svg?label=Chat&logo=Discord&colorB=7289da&style=flat`,
+    setup:
+      'Two different values: the numeric server id drives the online-member count (Server Settings → Widget → Enable Server Widget, then copy the Server ID), and the invite link is where the badge points. Without the widget enabled the badge reads "invite" instead of a count.',
+  },
+  {
+    id: 'prs-welcome',
+    title: 'PRs welcome',
+    group: 'community',
+    needs: [],
+    alt: 'PRs Welcome',
+    href: () =>
+      'https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request',
+    img: () => shieldsBadge('PRs-welcome', 'brightgreen'),
+    setup: 'Static. Worth backing with a CONTRIBUTING.md so the badge is not the only thing that says it.',
+  },
+  {
+    id: 'license',
+    title: 'License',
+    group: 'community',
+    needs: [],
+    alt: 'License',
+    href: (c) => `https://github.com/${c.repoSlug}/blob/${c.defaultBranch}/LICENSE.md`,
+    img: (c) => `https://img.shields.io/github/license/${c.repoSlug}`,
+    setup:
+      'Reads the license GitHub detected, which comes from a recognized LICENSE file at the repo root. A custom or modified license shows as "unknown" no matter what the file says.',
+  },
+  {
+    id: 'stack',
+    title: 'Tech stack chips',
+    group: 'stack',
+    needs: ['stack'],
+    alt: 'Tech stack',
+    href: () => '',
+    img: () => '',
+    setup:
+      'Plain static shields with a simple-icons logo — `?logo=<slug>` accepts any slug from simpleicons.org. Purely decorative: they say what the project is built with at a glance. Pass a comma-separated list (e.g. `--stack Claude,Cloudflare,Next.js`).',
+  },
+];
+
+/** Brand colors for the stack chips, so the common ones look right by default. */
+const STACK_COLORS = {
+  claude: 'D97757',
+  cloudflare: 'F38020',
+  'next.js': 'black',
+  react: '20232A',
+  typescript: '3178C6',
+  bun: '14151A',
+  vite: '646CFF',
+  vercel: 'black',
+  postgresql: '4169E1',
+  tailwindcss: '06B6D4',
+};
+
+/**
+ * @param {string} name
+ * @returns {string} an `<img>` chip for one stack entry
+ */
+export function stackChip(name) {
+  const key = name.trim().toLowerCase();
+  const color = STACK_COLORS[key] ?? '555555';
+  const logo = key.replace(/[.\s]/g, '');
+  return `<img src="${shieldsBadge(name.trim(), color, { logo, logoColor: 'white' })}" alt="${name.trim()}" />`;
+}
+
+/**
+ * Which badges can render with the context available, and which cannot.
+ *
+ * Reporting the skipped ones is the point: a badge silently missing from the
+ * README is indistinguishable from one you forgot to ask for.
+ *
+ * @param {BadgeContext} context
+ * @param {{ only?: string[], exclude?: string[] }} [options]
+ * @returns {{ included: typeof BADGES, skipped: { id: string, missing: string[] }[] }}
+ */
+export function selectBadges(context, options = {}) {
+  const { only, exclude = [] } = options;
+
+  const included = [];
+  const skipped = [];
+
+  for (const badge of BADGES) {
+    if (only && !only.includes(badge.id)) continue;
+    if (exclude.includes(badge.id)) continue;
+
+    const missing = badge.needs.filter((key) => !context[key]);
+    if (missing.length > 0) {
+      skipped.push({ id: badge.id, missing });
+      continue;
+    }
+
+    included.push(badge);
+  }
+
+  return { included, skipped };
+}
+
+/**
+ * Render one badge as the `<a><img></a>` pair it becomes in the README.
+ *
+ * @param {typeof BADGES[number]} badge
+ * @param {BadgeContext} context
+ * @returns {string}
+ */
+export function renderBadge(badge, context) {
+  if (badge.id === 'stack') {
+    return String(context.stack)
+      .split(',')
+      .filter(Boolean)
+      .map(stackChip)
+      .join(' ');
+  }
+
+  const height = badge.height ? ` height="${badge.height}"` : '';
+  const img = `<img${height} src="${badge.img(context)}" alt="${badge.alt}" />`;
+
+  const href = badge.href(context);
+  return href ? `<a href="${href}">${img}</a>` : img;
+}
+
+/**
+ * The whole badge block, grouped one row per `GROUPS` entry.
+ *
+ * @param {BadgeContext} context
+ * @param {{ only?: string[], exclude?: string[] }} [options]
+ * @returns {{ markdown: string, skipped: { id: string, missing: string[] }[] }}
+ */
+export function renderBadgeBlock(context, options = {}) {
+  const { included, skipped } = selectBadges(context, options);
+
+  const rows = GROUPS.map((group) =>
+    included
+      .filter((badge) => badge.group === group)
+      .map((badge) => `    ${renderBadge(badge, context)}`)
+      .join('\n'),
+  ).filter(Boolean);
+
+  const markdown = ['<p align="center">', rows.join('\n    <br />\n'), '</p>'].join('\n');
+
+  return { markdown, skipped };
+}

package/src/context.js

@@ -0,0 +1,228 @@
+/**
+ * Work out everything the templates need to be substituted with, from the repo
+ * itself, so the common case is one command and no flags.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+/**
+ * Walk up from `start` to the directory holding `.git`.
+ *
+ * Templating the wrong directory is the one failure that is annoying to undo —
+ * running from `packages/foo` must not scatter a `.github/` in there — so the
+ * root is found rather than assumed.
+ *
+ * @param {string} [start]
+ * @returns {string | null}
+ */
+export function findRepoRoot(start = process.cwd()) {
+  let dir = path.resolve(start);
+
+  for (;;) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * @param {string[]} args
+ * @param {string} cwd
+ * @returns {string} trimmed stdout, or '' if git failed
+ */
+function git(args, cwd) {
+  try {
+    return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * `owner/repo` from a remote URL, in any of the shapes git remotes come in:
+ * https, ssh, `git@`, with or without `.git`.
+ *
+ * @param {string} url
+ * @returns {string | null}
+ */
+export function parseRepoSlug(url) {
+  if (!url) return null;
+
+  const match = url.match(/(?:github\.com[/:])([^/]+)\/(.+?)(?:\.git)?$/);
+  if (!match) return null;
+
+  return `${match[1]}/${match[2]}`;
+}
+
+/**
+ * The default branch as the *remote* sees it, falling back to the current
+ * branch.
+ *
+ * This matters more than it looks: the CI status badge takes `?branch=`, and a
+ * badge pinned to the wrong branch shows a passing repo as failing (or worse,
+ * the reverse) for as long as nobody checks.
+ *
+ * @param {string} root
+ * @returns {string}
+ */
+export function detectDefaultBranch(root) {
+  const symbolic = git(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], root);
+  if (symbolic) return symbolic.replace(/^origin\//, '');
+
+  const current = git(['rev-parse', '--abbrev-ref', 'HEAD'], root);
+  // A detached HEAD reports "HEAD", which is not a branch name.
+  if (current && current !== 'HEAD') return current;
+
+  return 'main';
+}
+
+/**
+ * Which package manager the repo already uses. The workflows run its `install`,
+ * so guessing wrong means CI installs with a tool the lockfile is not for.
+ *
+ * @param {string} root
+ * @returns {'bun' | 'pnpm' | 'yarn' | 'npm'}
+ */
+export function detectPackageManager(root) {
+  const manifest = readJson(path.join(root, 'package.json'));
+  const declared = manifest?.packageManager;
+  if (typeof declared === 'string') {
+    const name = declared.split('@')[0];
+    if (['bun', 'pnpm', 'yarn', 'npm'].includes(name)) return name;
+  }
+
+  if (fs.existsSync(path.join(root, 'bun.lock')) || fs.existsSync(path.join(root, 'bun.lockb'))) return 'bun';
+  if (fs.existsSync(path.join(root, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(root, 'yarn.lock'))) return 'yarn';
+
+  return 'npm';
+}
+
+/**
+ * @param {string} file
+ * @returns {Record<string, any> | null}
+ */
+export function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The directory the workspace globs point at (`packages/*` -> `packages`),
+ * which the publish workflow needs for `git add` and for the build order.
+ *
+ * @param {Record<string, any> | null} manifest
+ * @returns {string}
+ */
+export function detectPackagesDir(manifest) {
+  const globs = Array.isArray(manifest?.workspaces)
+    ? manifest.workspaces
+    : (manifest?.workspaces?.packages ?? []);
+
+  const glob = globs.find((entry) => entry.endsWith('/*'));
+  return glob ? glob.slice(0, -2) : 'packages';
+}
+
+/**
+ * The package to advertise in the npm badges: the first non-private workspace
+ * package, or the root package if it is publishable.
+ *
+ * @param {string} root
+ * @param {string} packagesDir
+ * @returns {string | undefined}
+ */
+export function detectNpmPackage(root, packagesDir) {
+  const rootManifest = readJson(path.join(root, 'package.json'));
+  if (rootManifest?.name && !rootManifest.private) return rootManifest.name;
+
+  const dir = path.join(root, packagesDir);
+  if (!fs.existsSync(dir)) return undefined;
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory()) continue;
+    const pkg = readJson(path.join(dir, entry.name, 'package.json'));
+    if (pkg?.name && !pkg.private) return pkg.name;
+  }
+
+  return undefined;
+}
+
+/**
+ * Everything the templates and badges need, detected then overridden by flags.
+ *
+ * @param {{ cwd?: string, overrides?: Record<string, string | undefined> }} [options]
+ * @returns {Record<string, any>}
+ */
+export function buildContext(options = {}) {
+  const { cwd = process.cwd(), overrides = {} } = options;
+
+  const root = findRepoRoot(cwd) ?? path.resolve(cwd);
+  const manifest = readJson(path.join(root, 'package.json'));
+  const packagesDir = overrides.packagesDir ?? detectPackagesDir(manifest);
+
+  const repoSlug =
+    overrides.repoSlug ??
+    parseRepoSlug(git(['remote', 'get-url', 'origin'], root)) ??
+    undefined;
+
+  const [owner, repo] = repoSlug ? repoSlug.split('/') : [undefined, undefined];
+
+  const context = {
+    root,
+    repoSlug,
+    owner,
+    repo,
+    defaultBranch: overrides.defaultBranch ?? detectDefaultBranch(root),
+    packageManager: overrides.packageManager ?? detectPackageManager(root),
+    packagesDir,
+    packagesGlob: `${packagesDir}/*`,
+    npmPackage: overrides.npmPackage ?? detectNpmPackage(root, packagesDir),
+    workflowFile: overrides.workflowFile ?? 'tests.yml',
+    // Everything below has no sensible default — a badge that needs one of
+    // these is skipped until it is passed in.
+    doi: overrides.doi,
+    docsUrl: overrides.docsUrl,
+    apiUrl: overrides.apiUrl,
+    youtubeUrl: overrides.youtubeUrl,
+    uptimeUrl: overrides.uptimeUrl,
+    testReportUrl: overrides.testReportUrl,
+    discordId: overrides.discordId,
+    discordInvite: overrides.discordInvite,
+    stack: overrides.stack,
+    cloudflareDeploy: overrides.cloudflareDeploy,
+  };
+
+  return context;
+}
+
+/**
+ * Substitute `{{TOKEN}}` placeholders in a template file's text.
+ *
+ * Unknown tokens are left alone rather than replaced with `undefined`: a
+ * workflow with a visible `{{THING}}` in it is an obvious bug, while one that
+ * runs `bun install` as `undefined install` is a confusing one.
+ *
+ * @param {string} text
+ * @param {Record<string, any>} context
+ * @returns {string}
+ */
+export function substitute(text, context) {
+  const values = {
+    DEFAULT_BRANCH: context.defaultBranch,
+    PACKAGE_MANAGER: context.packageManager,
+    PACKAGES_DIR: context.packagesDir,
+    PACKAGES_GLOB: context.packagesGlob,
+    REPO_SLUG: context.repoSlug,
+    OWNER: context.owner,
+    REPO: context.repo,
+  };
+
+  return text.replace(/\{\{([A-Z_]+)\}\}/g, (match, token) =>
+    values[token] === undefined ? match : String(values[token]),
+  );
+}

package/src/index.js

@@ -0,0 +1,29 @@
+/**
+ * Public entry point. The CLI is the intended interface; these exports exist so
+ * the pieces can be scripted (generating a badge row for a docs site, checking
+ * a repo's workflows in a test) without shelling out.
+ */
+export {
+  BADGES,
+  GROUPS,
+  renderBadge,
+  renderBadgeBlock,
+  selectBadges,
+  shieldsBadge,
+  stackChip,
+} from './badges.js';
+
+export {
+  buildContext,
+  detectDefaultBranch,
+  detectNpmPackage,
+  detectPackageManager,
+  detectPackagesDir,
+  findRepoRoot,
+  parseRepoSlug,
+  substitute,
+} from './context.js';
+
+export { END_MARKER, START_MARKER, hasUnmarkedBadges, injectBadges } from './readme.js';
+
+export { planFiles, applyPlan } from './apply.js';

package/src/readme.js

@@ -0,0 +1,60 @@
+/**
+ * Put the badge block into a README without destroying what is already there.
+ *
+ * Badges are the one part of a README that gets regenerated, so they live
+ * between markers. Re-running the CLI replaces what is between them and touches
+ * nothing else — which is what makes it safe to run again after publishing a
+ * package or setting up Codecov.
+ */
+
+export const START_MARKER = '<!-- template-git-repo:badges:start -->';
+export const END_MARKER = '<!-- template-git-repo:badges:end -->';
+
+/**
+ * Replace the marked block, or insert one.
+ *
+ * With no markers present, the block goes at the very top — above the title —
+ * because that is where a badge row belongs and because inserting it anywhere
+ * else would require guessing at the document's structure.
+ *
+ * An existing unmarked badge row (a `<p align="center">` full of shields.io
+ * images at the top of the file) is left exactly where it is: silently deleting
+ * hand-written badges would be worse than a duplicate the author can see and
+ * remove.
+ *
+ * @param {string} readme current README text ('' for a new file)
+ * @param {string} block the rendered badge markdown
+ * @returns {{ content: string, action: 'replaced' | 'inserted' }}
+ */
+export function injectBadges(readme, block) {
+  const marked = [START_MARKER, block, END_MARKER].join('\n');
+
+  const start = readme.indexOf(START_MARKER);
+  const end = readme.indexOf(END_MARKER);
+
+  if (start !== -1 && end !== -1 && end > start) {
+    return {
+      content: readme.slice(0, start) + marked + readme.slice(end + END_MARKER.length),
+      action: 'replaced',
+    };
+  }
+
+  if (readme.trim() === '') {
+    return { content: `${marked}\n`, action: 'inserted' };
+  }
+
+  return { content: `${marked}\n\n${readme.replace(/^\n+/, '')}`, action: 'inserted' };
+}
+
+/**
+ * Whether a README already carries a badge row this CLI did not write.
+ *
+ * @param {string} readme
+ * @returns {boolean}
+ */
+export function hasUnmarkedBadges(readme) {
+  if (readme.includes(START_MARKER)) return false;
+
+  const head = readme.slice(0, 4000);
+  return /img\.shields\.io|badge\.svg/.test(head);
+}