template-git-repo 0.1.0

package/docs/BADGES.md

@@ -0,0 +1,221 @@
+<!-- Generated by scripts/generate-badge-docs.mjs from src/badges.js — edit the catalog, not this file. -->
+
+# Badge setup
+
+Every badge in the template, what it actually measures, and what you have to do
+outside this repo before it shows anything real.
+
+The CLI leaves out any badge whose inputs it does not have, and prints which ones
+it left out and why. Re-run it with the flag from the table below to add one:
+
+```bash
+bunx template-git-repo --badges-only --discord-id 1110227955554209923 --discord-invite https://discord.gg/xxxx
+```
+
+The block lives between `<!-- template-git-repo:badges:start -->` and
+`<!-- template-git-repo:badges:end -->` in your README. Re-running replaces what is
+between the markers and nothing else, so it is safe to run again after you publish a
+package or finish setting up Codecov.
+
+## Index
+
+| Badge | Needs | Flag |
+| --- | --- | --- |
+| [Zenodo DOI](#doi) `doi` | doi | `--doi <10.5281/zenodo.NNNNNNN>` |
+| [Ask DeepWiki](#deepwiki) `deepwiki` | — | on by default |
+| [Documentation](#docs) `docs` | docsUrl | `--docs <url>` |
+| [API reference](#api) `api` | apiUrl | `--api <url>` |
+| [YouTube demo](#youtube) `youtube` | youtubeUrl | `--youtube <url>` |
+| [Deploy to Cloudflare Workers](#deploy-cloudflare) `deploy-cloudflare` | cloudflareDeploy | `--cloudflare-deploy` |
+| [GitHub stars](#stars) `stars` | — | on by default |
+| [npm monthly downloads](#npm-downloads) `npm-downloads` | npmPackage | `--npm-package <name>` |
+| [npm version](#npm-version) `npm-version` | npmPackage | `--npm-package <name>` |
+| [Code coverage](#codecov) `codecov` | — | on by default |
+| [CI status](#workflow) `workflow` | workflowFile | `--workflow <file>` |
+| [Hosted test report](#test-report) `test-report` | testReportUrl | `--test-report <url>` |
+| [Uptime](#uptime) `uptime` | uptimeUrl | `--uptime <url>` |
+| [Commit activity](#commit-activity) `commit-activity` | — | on by default |
+| [Last commit](#last-commit) `last-commit` | — | on by default |
+| [Discord](#discord) `discord` | discordId, discordInvite | `--discord-id <id>` `--discord-invite <url>` |
+| [PRs welcome](#prs-welcome) `prs-welcome` | — | on by default |
+| [License](#license) `license` | — | on by default |
+| [Tech stack chips](#stack) `stack` | stack | `--stack <A,B,C>` |
+
+## Identity — what this project is
+
+### doi
+
+**Zenodo DOI**
+
+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.
+
+Enable with: `--doi <10.5281/zenodo.NNNNNNN>`
+
+### deepwiki
+
+**Ask DeepWiki**
+
+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.
+
+Included by default — no configuration needed.
+
+### docs
+
+**Documentation**
+
+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.
+
+Enable with: `--docs <url>`
+
+### api
+
+**API reference**
+
+Point this at your OpenAPI / Swagger page. Static badge, same caveat as Docs.
+
+Enable with: `--api <url>`
+
+### youtube
+
+**YouTube demo**
+
+A demo video does more for a README than three paragraphs. Any YouTube URL works.
+
+Enable with: `--youtube <url>`
+
+### deploy-cloudflare
+
+**Deploy to Cloudflare Workers**
+
+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.
+
+Enable with: `--cloudflare-deploy`
+
+## Quality — is it working, is it tested, is it shipped
+
+### npm-downloads
+
+**npm monthly downloads**
+
+Requires at least one published version. In a monorepo pick the package you want to advertise — the badge counts one package, not the workspace.
+
+Enable with: `--npm-package <name>`
+
+### npm-version
+
+**npm version**
+
+Shows the `latest` dist-tag. Publishing under a different tag will not move it.
+
+Enable with: `--npm-package <name>`
+
+### codecov
+
+**Code coverage**
+
+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.
+
+Included by default — no configuration needed.
+
+### workflow
+
+**CI status**
+
+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.
+
+Enable with: `--workflow <file>`
+
+### test-report
+
+**Hosted test report**
+
+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.
+
+Enable with: `--test-report <url>`
+
+### uptime
+
+**Uptime**
+
+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.
+
+Enable with: `--uptime <url>`
+
+## Community — is it alive, can I join
+
+### stars
+
+**GitHub stars**
+
+Nothing to configure. Public repos only — shields.io cannot read a private repo.
+
+Included by default — no configuration needed.
+
+### commit-activity
+
+**Commit activity**
+
+Nothing to configure. Commits per month — a quiet month reads as an abandoned project, which is worth knowing before you add it.
+
+Included by default — no configuration needed.
+
+### last-commit
+
+**Last commit**
+
+Nothing to configure. Same caveat as commit activity.
+
+Included by default — no configuration needed.
+
+### discord
+
+**Discord**
+
+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.
+
+Enable with: `--discord-id <id>` `--discord-invite <url>`
+
+### prs-welcome
+
+**PRs welcome**
+
+Static. Worth backing with a CONTRIBUTING.md so the badge is not the only thing that says it.
+
+Included by default — no configuration needed.
+
+### license
+
+**License**
+
+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.
+
+Included by default — no configuration needed.
+
+## Stack — what it is built with
+
+### stack
+
+**Tech stack chips**
+
+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`).
+
+Enable with: `--stack <A,B,C>`
+
+## Removing one
+
+```bash
+bunx template-git-repo --badges-only --exclude commit-activity,last-commit
+```
+
+Or edit the block between the markers directly — the CLI only rewrites it when you
+run it again.
+
+## Why some badges stay grey
+
+| Badge reads | Almost always means |
+| --- | --- |
+| Codecov: `unknown` | No upload has landed yet. Check the Codecov dashboard, not the badge — a missing `CODECOV_TOKEN` and a repo that was never added look identical from here. |
+| CI: `no status` | The workflow filename in the badge URL does not match a file in `.github/workflows/`, or it has never run on the branch in `?branch=`. |
+| npm: `invalid` | The package name is not on the registry, or it is scoped and the scope is missing from the URL. |
+| Discord: `invite` instead of a count | The server widget is off. Server Settings → Widget → Enable Server Widget. |
+| Stars/last-commit: `repo not found` | shields.io cannot read private repos. |

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "template-git-repo",
+  "version": "0.1.0",
+  "description": "One command to set up a repo with GitHub Actions, README badges, Turborepo and Codecov — the CI setup from qwksearch-research-agent, as a template",
+  "type": "module",
+  "bin": {
+    "template-git-repo": "bin/template-git-repo.js"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./badges": "./src/badges.js"
+  },
+  "scripts": {
+    "docs:badges": "node scripts/generate-badge-docs.mjs",
+    "test": "vitest run",
+    "test:ci": "vitest run --coverage",
+    "test:coverage": "vitest run --coverage",
+    "coverage": "vitest run --coverage",
+    "test:watch": "vitest"
+  },
+  "files": [
+    "bin",
+    "src",
+    "template",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "github-actions",
+    "template",
+    "badges",
+    "shields",
+    "turborepo",
+    "monorepo",
+    "codecov",
+    "npm-publish",
+    "ci",
+    "scaffold"
+  ],
+  "author": "vtempest",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OpenSourceAGI/dev-tools-starter-agent.git",
+    "directory": "packages/template-git-repo"
+  },
+  "homepage": "https://github.com/OpenSourceAGI/dev-tools-starter-agent/tree/master/packages/template-git-repo",
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.0",
+    "vitest": "^4.1.0",
+    "yaml": "^2.9.0"
+  }
+}

package/src/apply.js

@@ -0,0 +1,164 @@
+/**
+ * Turn the template directory into a list of file operations, then (separately)
+ * carry them out.
+ *
+ * The split is what makes `--dry-run` honest: the same plan is printed and
+ * applied, so what the dry run shows is exactly what a real run does, rather
+ * than a second implementation that can drift from the first.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { substitute } from './context.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+/** The shipped template tree. */
+export const TEMPLATE_DIR = path.join(HERE, '..', 'template');
+
+/**
+ * Every file under `dir`, relative to it, depth-first and sorted.
+ *
+ * @param {string} dir
+ * @param {string} [prefix]
+ * @returns {string[]}
+ */
+export function walk(dir, prefix = '') {
+  if (!fs.existsSync(dir)) return [];
+
+  const files = [];
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      files.push(...walk(path.join(dir, entry.name), relative));
+    } else {
+      files.push(relative);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Decide what happens to each template file.
+ *
+ * Existing files are skipped rather than overwritten unless `force` is set.
+ * A repo that already has a `turbo.json` has it for a reason, and clobbering a
+ * tuned workflow with a generic one is the kind of "help" that costs an
+ * afternoon.
+ *
+ * @param {object} options
+ * @param {Record<string, any>} options.context
+ * @param {string} [options.templateDir]
+ * @param {boolean} [options.force]
+ * @param {string[]} [options.include] relative template paths to consider; all by default
+ * @returns {{ path: string, absolute: string, content: string, action: 'create' | 'overwrite' | 'skip' }[]}
+ */
+export function planFiles({ context, templateDir = TEMPLATE_DIR, force = false, include }) {
+  const plan = [];
+
+  for (const relative of walk(templateDir)) {
+    if (include && !include.some((prefix) => relative === prefix || relative.startsWith(`${prefix}/`))) {
+      continue;
+    }
+
+    const absolute = path.join(context.root, relative);
+    const content = substitute(fs.readFileSync(path.join(templateDir, relative), 'utf8'), context);
+
+    let action = 'create';
+    if (fs.existsSync(absolute)) {
+      const existing = fs.readFileSync(absolute, 'utf8');
+      // An identical file is a skip whatever `force` says — reporting it as an
+      // overwrite would make a no-op run look like it changed something.
+      action = existing === content ? 'skip' : force ? 'overwrite' : 'skip';
+    }
+
+    plan.push({ path: relative, absolute, content, action });
+  }
+
+  return plan;
+}
+
+/**
+ * @param {ReturnType<typeof planFiles>} plan
+ * @param {{ dryRun?: boolean }} [options]
+ * @returns {{ written: string[], skipped: string[] }}
+ */
+export function applyPlan(plan, options = {}) {
+  const { dryRun = false } = options;
+
+  const written = [];
+  const skipped = [];
+
+  for (const entry of plan) {
+    if (entry.action === 'skip') {
+      skipped.push(entry.path);
+      continue;
+    }
+
+    if (!dryRun) {
+      fs.mkdirSync(path.dirname(entry.absolute), { recursive: true });
+      fs.writeFileSync(entry.absolute, entry.content);
+      // The workflows call these directly; a script that is not executable
+      // fails at the least convenient moment.
+      if (entry.path.endsWith('.mjs')) fs.chmodSync(entry.absolute, 0o755);
+    }
+
+    written.push(entry.path);
+  }
+
+  return { written, skipped };
+}
+
+/**
+ * The turbo scripts and devDependency the template's workflows assume.
+ *
+ * Merged into the root package.json rather than written over it: an existing
+ * script keeps its definition, since a repo's own `build` almost certainly does
+ * something this template cannot know about.
+ */
+export const TURBO_SCRIPTS = {
+  build: 'turbo run build',
+  dev: 'turbo run dev',
+  lint: 'turbo run lint',
+  typecheck: 'turbo run typecheck',
+  test: 'turbo run test',
+  'test:coverage': 'turbo run test:coverage',
+  'test:watch': 'turbo run test:watch',
+  clean: 'turbo run clean && rm -rf .turbo node_modules',
+};
+
+/**
+ * @param {Record<string, any>} manifest parsed root package.json
+ * @param {{ packagesDir?: string, turboVersion?: string }} [options]
+ * @returns {{ manifest: Record<string, any>, changes: string[] }}
+ */
+export function wireTurbo(manifest, options = {}) {
+  const { packagesDir = 'packages', turboVersion = '^2.10.12' } = options;
+
+  const next = structuredClone(manifest);
+  const changes = [];
+
+  next.scripts ??= {};
+  for (const [name, command] of Object.entries(TURBO_SCRIPTS)) {
+    if (next.scripts[name]) continue;
+    next.scripts[name] = command;
+    changes.push(`scripts.${name}`);
+  }
+
+  next.devDependencies ??= {};
+  if (!next.devDependencies.turbo) {
+    next.devDependencies.turbo = turboVersion;
+    changes.push('devDependencies.turbo');
+  }
+
+  // Turbo needs to know what the workspace is; without `workspaces` it treats
+  // the repo as a single package and every `--filter` silently matches nothing.
+  if (!next.workspaces) {
+    next.workspaces = [`${packagesDir}/*`, 'apps/*'];
+    changes.push('workspaces');
+  }
+
+  return { manifest: next, changes };
+}