template-git-repo 0.1.11 → 0.1.12

package/README.md

@@ -1,3 +1,25 @@
+<!-- template-git-repo:badges:start -->
+<p align="center">
+    <a href="https://starterdocs.vtempest.workers.dev/docs/packages/template-git-repo"><img src="https://img.shields.io/badge/Docs-blue?logo=ReadTheDocs&logoColor=white" alt="Documentation" /></a>
+    <a href="https://stackblitz.com/github/OpenSourceAGI/dev-tools-starter-agent/tree/master/packages/template-git-repo"><img height="20px" src="https://developer.stackblitz.com/img/open_in_stackblitz.svg" alt="Open in StackBlitz" /></a>
+    <br />
+    <a href="https://www.npmjs.com/package/template-git-repo"><img src="https://img.shields.io/npm/dm/template-git-repo.svg" alt="NPM Monthly Downloads" /></a>
+    <a href="https://www.npmjs.com/package/template-git-repo"><img src="https://img.shields.io/npm/v/template-git-repo.svg" alt="npm version" /></a>
+    <a href="https://www.npmjs.com/package/template-git-repo"><img src="https://img.shields.io/npm/dt/template-git-repo.svg" alt="NPM Total Downloads" /></a>
+    <a href="https://www.npmjs.com/package/template-git-repo"><img src="https://img.shields.io/npm/types/template-git-repo" alt="TypeScript types" /></a>
+    <a href="https://packagephobia.com/result?p=template-git-repo"><img src="https://packagephobia.com/badge?p=template-git-repo" alt="Install size" /></a>
+    <a href="https://app.codecov.io/gh/OpenSourceAGI/dev-tools-starter-agent/flags"><img src="https://img.shields.io/codecov/c/github/OpenSourceAGI/dev-tools-starter-agent?flag=template-git-repo&label=template-git-repo%20coverage&logo=codecov&logoColor=white" alt="Coverage" /></a>
+</p>
+<!-- template-git-repo:badges:end -->
+
+<!-- skills:install:start -->
+**🤖 Agent skills**
+<br />
+`npx skills@latest add https://github.com/OpenSourceAGI/dev-tools-starter-agent --skill template-git-repo` ([what it covers](../../skills/template-git-repo/SKILL.md))
+<br />
+`npx skills@latest add https://github.com/OpenSourceAGI/dev-tools-starter-agent --skill repo-badges` ([what it covers](../../skills/repo-badges/SKILL.md))
+<!-- skills:install:end -->
+
 # template-git-repo
 
 One command to give a repository the CI, publishing, badges and Turborepo wiring

package/bin/template-git-repo.js

@@ -56,6 +56,7 @@ Badge inputs (each enables the badge that needs it)
   --youtube <url>            --uptime <url>        --test-report <url>
   --discord-id <id>          --discord-invite <url>
   --stack <A,B,C>            --cloudflare-deploy
+  --stackblitz <url>         --codecov-flag <name>
   --exclude <id,id>          --only <id,id>
 
   Badge ids: ${BADGES.map((b) => b.id).join(', ')}
@@ -116,6 +117,8 @@ function overridesFrom(flags) {
     discordInvite: text('discord-invite'),
     stack: text('stack'),
     cloudflareDeploy: flags['cloudflare-deploy'] ? 'true' : undefined,
+    stackblitzUrl: text('stackblitz'),
+    codecovFlag: text('codecov-flag'),
   };
 }
 

package/docs/BADGES.md

@@ -27,10 +27,15 @@ package or finish setting up Codecov.
 | [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` |
+| [Open in StackBlitz](#stackblitz) `stackblitz` | stackblitzUrl | `--stackblitz <url>` |
 | [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>` |
+| [npm total downloads](#npm-total-downloads) `npm-total-downloads` | npmPackage | `--npm-package <name>` |
+| [TypeScript types](#npm-types) `npm-types` | npmPackage | `--npm-package <name>` |
+| [Install size](#install-size) `install-size` | npmPackage | `--npm-package <name>` |
 | [Code coverage](#codecov) `codecov` | — | on by default |
+| [Coverage for one package](#codecov-flag) `codecov-flag` | codecovFlag | `--codecov-flag <name>` |
 | [CI status](#workflow) `workflow` | workflowFile | `--workflow <file>` |
 | [Hosted test report](#test-report) `test-report` | testReportUrl | `--test-report <url>` |
 | [Uptime](#uptime) `uptime` | uptimeUrl | `--uptime <url>` |
@@ -91,6 +96,14 @@ The repo must contain a wrangler.toml (or wrangler.jsonc) at the path the button
 
 Enable with: `--cloudflare-deploy`
 
+### stackblitz
+
+**Open in StackBlitz**
+
+Nothing to configure — StackBlitz imports a public repo straight from a URL: `https://stackblitz.com/github/<owner>/<repo>/tree/<branch>/<path>`. Point it at a directory that boots on its own (a package with its own package.json, or an `examples/` folder), because StackBlitz installs from the manifest at that path and a bare monorepo root will not run. Node APIs need the WebContainer runtime, which means the directory must be ESM and its deps must be installable from npm.
+
+Enable with: `--stackblitz <url>`
+
 ## Quality — is it working, is it tested, is it shipped
 
 ### npm-downloads
@@ -109,6 +122,30 @@ Shows the `latest` dist-tag. Publishing under a different tag will not move it.
 
 Enable with: `--npm-package <name>`
 
+### npm-total-downloads
+
+**npm total downloads**
+
+All-time downloads for one package. Worth pairing with the monthly count rather than showing alone: a large total and a flat month say different things, and only the monthly number tells you the project is still being installed.
+
+Enable with: `--npm-package <name>`
+
+### npm-types
+
+**TypeScript types**
+
+Reads the published tarball: it says "TypeScript" when the manifest has a `types`/`typings` field pointing at a real `.d.ts`, and stays grey when the declarations were left out of `files`. Publish once and check it — this is the badge that catches a build that shipped JS without its types.
+
+Enable with: `--npm-package <name>`
+
+### install-size
+
+**Install size**
+
+Nothing to configure, but read what it measures: packagephobia reports what `npm install` writes to disk, dependencies included — not the bundled browser size. A package whose one dependency is an AWS SDK client looks enormous here and tree-shakes to very little in a bundler.
+
+Enable with: `--npm-package <name>`
+
 ### codecov
 
 **Code coverage**
@@ -117,6 +154,14 @@ Add the repo at codecov.io, copy its upload token into a CODECOV_TOKEN repositor
 
 Included by default — no configuration needed.
 
+### codecov-flag
+
+**Coverage for one package**
+
+The repo-wide number is the wrong one to put on a package README in a monorepo — it mixes in every other package. This one narrows to a single Codecov flag, so it needs that flag to exist: an entry under `flag_management.individual_flags` in codecov.yml, and an upload that passes `flags: <name>` (tests.yml does, from its matrix). The flag name has to match both exactly, or the badge reads "unknown" while the repo-wide badge looks fine.
+
+Enable with: `--codecov-flag <name>`
+
 ### workflow
 
 **CI status**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "template-git-repo",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "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": {

package/src/badges.js

@@ -107,6 +107,18 @@ export const BADGES = [
       '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: 'stackblitz',
+    title: 'Open in StackBlitz',
+    group: 'identity',
+    needs: ['stackblitzUrl'],
+    alt: 'Open in StackBlitz',
+    href: (c) => c.stackblitzUrl,
+    img: () => 'https://developer.stackblitz.com/img/open_in_stackblitz.svg',
+    setup:
+      'Nothing to configure — StackBlitz imports a public repo straight from a URL: `https://stackblitz.com/github/<owner>/<repo>/tree/<branch>/<path>`. Point it at a directory that boots on its own (a package with its own package.json, or an `examples/` folder), because StackBlitz installs from the manifest at that path and a bare monorepo root will not run. Node APIs need the WebContainer runtime, which means the directory must be ESM and its deps must be installable from npm.',
+    height: '20px',
+  },
   {
     id: 'stars',
     title: 'GitHub stars',
@@ -138,6 +150,39 @@ export const BADGES = [
     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: 'npm-total-downloads',
+    title: 'npm total downloads',
+    group: 'quality',
+    needs: ['npmPackage'],
+    alt: 'NPM Total Downloads',
+    href: (c) => `https://www.npmjs.com/package/${c.npmPackage}`,
+    img: (c) => `https://img.shields.io/npm/dt/${c.npmPackage}.svg`,
+    setup:
+      'All-time downloads for one package. Worth pairing with the monthly count rather than showing alone: a large total and a flat month say different things, and only the monthly number tells you the project is still being installed.',
+  },
+  {
+    id: 'npm-types',
+    title: 'TypeScript types',
+    group: 'quality',
+    needs: ['npmPackage'],
+    alt: 'TypeScript types',
+    href: (c) => `https://www.npmjs.com/package/${c.npmPackage}`,
+    img: (c) => `https://img.shields.io/npm/types/${c.npmPackage}`,
+    setup:
+      'Reads the published tarball: it says "TypeScript" when the manifest has a `types`/`typings` field pointing at a real `.d.ts`, and stays grey when the declarations were left out of `files`. Publish once and check it — this is the badge that catches a build that shipped JS without its types.',
+  },
+  {
+    id: 'install-size',
+    title: 'Install size',
+    group: 'quality',
+    needs: ['npmPackage'],
+    alt: 'Install size',
+    href: (c) => `https://packagephobia.com/result?p=${c.npmPackage}`,
+    img: (c) => `https://packagephobia.com/badge?p=${c.npmPackage}`,
+    setup:
+      'Nothing to configure, but read what it measures: packagephobia reports what `npm install` writes to disk, dependencies included — not the bundled browser size. A package whose one dependency is an AWS SDK client looks enormous here and tree-shakes to very little in a bundler.',
+  },
   {
     id: 'codecov',
     title: 'Code coverage',
@@ -149,6 +194,20 @@ export const BADGES = [
     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: 'codecov-flag',
+    title: 'Coverage for one package',
+    group: 'quality',
+    needs: ['codecovFlag'],
+    alt: 'Coverage',
+    href: (c) => `https://app.codecov.io/gh/${c.repoSlug}/flags`,
+    img: (c) =>
+      `https://img.shields.io/codecov/c/github/${c.repoSlug}?flag=${encodeURIComponent(
+        String(c.codecovFlag),
+      )}&label=${encodeURIComponent(`${c.codecovFlag} coverage`)}&logo=codecov&logoColor=white`,
+    setup:
+      'The repo-wide number is the wrong one to put on a package README in a monorepo — it mixes in every other package. This one narrows to a single Codecov flag, so it needs that flag to exist: an entry under `flag_management.individual_flags` in codecov.yml, and an upload that passes `flags: <name>` (tests.yml does, from its matrix). The flag name has to match both exactly, or the badge reads "unknown" while the repo-wide badge looks fine.',
+  },
   {
     id: 'workflow',
     title: 'CI status',

package/src/context.js

@@ -71,6 +71,14 @@ export function detectDefaultBranch(root) {
   const symbolic = git(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], root);
   if (symbolic) return symbolic.replace(/^origin\//, '');
 
+  // origin/HEAD is unset in plenty of clones (a shallow CI checkout, anything
+  // cloned with --single-branch). Falling straight through to the current branch
+  // there is how badges end up pinned to whatever feature branch they were
+  // generated on, so try the conventional names on the remote first.
+  for (const name of ['main', 'master', 'canary']) {
+    if (git(['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${name}`], root)) return name;
+  }
+
   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;
@@ -195,6 +203,8 @@ export function buildContext(options = {}) {
     discordInvite: overrides.discordInvite,
     stack: overrides.stack,
     cloudflareDeploy: overrides.cloudflareDeploy,
+    stackblitzUrl: overrides.stackblitzUrl,
+    codecovFlag: overrides.codecovFlag,
   };
 
   return context;