template-git-repo 0.1.0

package/template/codecov.yml

@@ -0,0 +1,46 @@
+# Codecov configuration.
+#
+# Every workspace package uploads its own lcov report under its own flag (see
+# .github/workflows/tests.yml), so the dashboard shows a per-package percentage
+# alongside the project total.
+
+codecov:
+  require_ci_to_pass: false
+
+coverage:
+  precision: 2
+  round: down
+  range: "50...90"
+
+  status:
+    project:
+      default:
+        # Report coverage without failing the build while the suites are still
+        # being filled in. Drop `informational` once the numbers settle and you
+        # want a coverage drop to actually block a merge.
+        target: auto
+        threshold: 2%
+        informational: true
+    patch:
+      default:
+        target: 70%
+        threshold: 5%
+        informational: true
+
+# `carryforward` keeps a package's last known coverage when a PR does not touch
+# it. Without it, every package not covered by the current upload reads as 0%
+# and the project total collapses on every partial run.
+flag_management:
+  default_rules:
+    carryforward: true
+    statuses:
+      - type: project
+        target: auto
+        threshold: 2%
+        informational: true
+
+comment:
+  layout: "condensed_header, diff, flags, components, condensed_files"
+  behavior: default
+  require_changes: true
+  hide_project_coverage: false

package/template/scripts/list-test-packages.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+/**
+ * Emit the GitHub Actions matrix for `.github/workflows/tests.yml`.
+ *
+ * A hand-written matrix fails silently: a package added to the repo but not to
+ * the matrix is simply never tested, and nothing goes red to say so. This reads
+ * the workspace globs out of the root package.json instead, so the matrix is
+ * whatever the repo actually contains.
+ *
+ * Each entry gets:
+ *   name          the package name, for `turbo --filter`
+ *   dir           its directory, for `working-directory`
+ *   flag          the Codecov flag — the directory basename, which is what a
+ *                 human reading the Codecov dashboard expects to see
+ *   script        `test:coverage` if it exists, else `test`
+ *   allowFailure  from `"ci": { "allowFailure": true }` in its package.json
+ *
+ * Output is GitHub Actions `$GITHUB_OUTPUT` key=value lines:
+ *   matrix={"include":[...]}
+ *   empty=true|false
+ *
+ * `empty` exists because GitHub fails a job whose matrix has no entries, which
+ * would make a repo with no test suites look broken rather than untested.
+ *
+ * Usage: node scripts/list-test-packages.mjs [rootDir]
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/** Scripts that count as "this package has a suite", best first. */
+const TEST_SCRIPTS = ['test:coverage', 'test:ci', 'test'];
+
+/**
+ * Expand the `workspaces` field into the directories it names.
+ *
+ * Only the one glob shape workspaces actually use in practice is supported —
+ * a trailing `/*` — because anything cleverer would need a glob dependency in
+ * a script that must run before `install`.
+ *
+ * @param {string} root repo root
+ * @returns {string[]} directories relative to the repo root
+ */
+export function workspaceDirectories(root = '.') {
+  const manifestPath = path.join(root, 'package.json');
+  if (!fs.existsSync(manifestPath)) return [];
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch {
+    return [];
+  }
+
+  // npm/bun accept both `workspaces: []` and `workspaces: { packages: [] }`.
+  const globs = Array.isArray(manifest.workspaces)
+    ? manifest.workspaces
+    : (manifest.workspaces?.packages ?? []);
+
+  const directories = [];
+
+  for (const glob of globs) {
+    if (!glob.endsWith('/*')) {
+      if (fs.existsSync(path.join(root, glob))) directories.push(glob);
+      continue;
+    }
+
+    const parent = glob.slice(0, -2);
+    const parentPath = path.join(root, parent);
+    if (!fs.existsSync(parentPath)) continue;
+
+    for (const entry of fs.readdirSync(parentPath, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      directories.push(`${parent}/${entry.name}`);
+    }
+  }
+
+  return directories.sort();
+}
+
+/**
+ * @param {string} [root]
+ * @returns {{ name: string, dir: string, flag: string, script: string, allowFailure: boolean }[]}
+ */
+export function testablePackages(root = '.') {
+  const entries = [];
+
+  for (const dir of workspaceDirectories(root)) {
+    const manifestPath = path.join(root, dir, 'package.json');
+    if (!fs.existsSync(manifestPath)) continue;
+
+    let pkg;
+    try {
+      pkg = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    } catch {
+      console.error(`Skipping ${manifestPath}: not valid JSON`);
+      continue;
+    }
+    if (!pkg.name) continue;
+
+    const script = TEST_SCRIPTS.find((candidate) => pkg.scripts?.[candidate]);
+    if (!script) continue;
+
+    entries.push({
+      name: pkg.name,
+      dir,
+      flag: path.basename(dir),
+      script,
+      allowFailure: Boolean(pkg.ci?.allowFailure),
+    });
+  }
+
+  return entries;
+}
+
+/**
+ * @param {{ name: string }[]} packages
+ * @returns {string} the `$GITHUB_OUTPUT` lines, newline-terminated
+ */
+export function formatOutput(packages) {
+  return [
+    `matrix=${JSON.stringify({ include: packages })}`,
+    `empty=${packages.length === 0}`,
+    '',
+  ].join('\n');
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  const packages = testablePackages(process.argv[2]);
+  for (const entry of packages) {
+    console.error(`✓ ${entry.name} (${entry.dir}) via ${entry.script}`);
+  }
+  if (packages.length === 0) {
+    console.error('No workspace package declares a test script — the test matrix is empty.');
+  }
+  process.stdout.write(formatOutput(packages));
+}

package/template/scripts/next-free-version.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * Pick the next version npm will actually accept for a package.
+ *
+ * The publish workflow used to bump one patch above whichever was higher, the
+ * local version or the registry's `latest` dist-tag, and assume the result was
+ * free. It is not: the registry refuses a PUT for any version it has *ever*
+ * seen, and plenty of those are invisible to `latest`.
+ *
+ *   npm error code E409
+ *   npm error 409 Conflict - PUT https://registry.npmjs.org/<package>
+ *     - Cannot publish over previously staged version "0.1.275".
+ *
+ * A version reaches that state when a publish is interrupted part-way, when it
+ * was published and later unpublished, or when it only ever carried a dist-tag
+ * other than `latest`. Six packages hit this in a single run of the workflow
+ * this script was written for, each having "bumped" straight onto a number the
+ * registry had already reserved.
+ *
+ * So treat the registry as the source of truth for which numbers are spent.
+ * `versions` lists what is currently published; `time` additionally keeps an
+ * entry for every version that ever existed, including staged and unpublished
+ * ones — the exact numbers `latest` cannot see. The union of the two is the
+ * taken set.
+ *
+ * Usage: node scripts/next-free-version.mjs <package-name> <local-version>
+ *   Prints the next free version, always strictly above <local-version>. If
+ *   the registry says nothing about the package (a first publish, or an
+ *   unreachable registry) that is just <local-version> plus a patch.
+ */
+import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+
+/** A plain `major.minor.patch` release — what every package here publishes. */
+const RELEASE = /^(\d+)\.(\d+)\.(\d+)$/;
+
+/**
+ * Compare two `major.minor.patch` versions numerically.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {number} negative if a < b, 0 if equal, positive if a > b
+ */
+export function compareVersions(a, b) {
+  const left = a.split('.').map(Number);
+  const right = b.split('.').map(Number);
+
+  for (let i = 0; i < 3; i++) {
+    const diff = (left[i] || 0) - (right[i] || 0);
+    if (diff !== 0) return diff;
+  }
+
+  return 0;
+}
+
+/**
+ * @param {string} version
+ * @returns {string} the same version with its patch incremented
+ */
+export function bumpPatch(version) {
+  const parts = version.split('.').map(Number);
+  parts[2] = (parts[2] || 0) + 1;
+  return parts.slice(0, 3).join('.');
+}
+
+/**
+ * Every version number the registry has ever handed out for a package.
+ *
+ * `time` is the important half: npm keeps a timestamp for versions that are no
+ * longer listed in `versions` (unpublished, or staged by a publish that never
+ * finished), and those are exactly the ones that answer a fresh PUT with E409.
+ *
+ * @param {{ versions?: string[] | string, time?: Record<string, string> }} packument
+ * @returns {Set<string>}
+ */
+export function takenVersions(packument) {
+  const taken = new Set();
+  if (!packument) return taken;
+
+  // `npm view <name> versions --json` collapses a single-version package to a
+  // bare string rather than a one-element array.
+  const versions = packument.versions;
+  for (const version of Array.isArray(versions)
+    ? versions
+    : versions
+      ? [versions]
+      : []) {
+    if (RELEASE.test(version)) taken.add(version);
+  }
+
+  // `time` also carries `created`, `modified` and (for a wholly unpublished
+  // package) `unpublished`; only the version-shaped keys matter here.
+  for (const key of Object.keys(packument.time || {})) {
+    if (RELEASE.test(key)) taken.add(key);
+  }
+
+  return taken;
+}
+
+/**
+ * The lowest free version that is strictly above both `local` and everything
+ * the registry has ever spent.
+ *
+ * Always a bump, never `local` itself: both callers already know `local`
+ * cannot be published — the workflow reaches here either because that version
+ * is on npm with different content, or because a publish attempt just came
+ * back E409 for a version the registry will not admit to knowing.
+ *
+ * @param {string} local version in the package's own package.json
+ * @param {Set<string>} taken every version the registry has ever seen
+ * @returns {string}
+ */
+export function nextFreeVersion(local, taken) {
+  let highest = RELEASE.test(local) ? local : '0.0.0';
+  for (const version of taken) {
+    if (compareVersions(version, highest) > 0) highest = version;
+  }
+
+  let next = bumpPatch(highest);
+  // A gap in the taken set can only be below `highest`, so this loop normally
+  // runs zero times; it is here so a registry that reports versions out of
+  // order still cannot produce a number that is already spent.
+  while (taken.has(next)) next = bumpPatch(next);
+
+  return next;
+}
+
+/**
+ * Ask npm for a package's published versions and its full release timeline.
+ *
+ * A package that has never been published (E404) and an unreachable registry
+ * look the same from here: both yield an empty packument, so the answer comes
+ * from the local version alone.
+ *
+ * @param {string} name
+ * @param {(cmd: string, args: string[]) => string} [run] injection point for tests
+ * @returns {{ versions?: string[], time?: Record<string, string> }}
+ */
+export function fetchPackument(name, run = defaultRun) {
+  let raw;
+  try {
+    raw = run('npm', ['view', name, 'versions', 'time', '--json']);
+  } catch {
+    return {};
+  }
+
+  if (!raw || !raw.trim()) return {};
+
+  try {
+    return JSON.parse(raw) || {};
+  } catch {
+    return {};
+  }
+}
+
+function defaultRun(cmd, args) {
+  return execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) {
+  const [name, local] = process.argv.slice(2);
+
+  if (!name || !local) {
+    console.error('Usage: node scripts/next-free-version.mjs <package-name> <local-version>');
+    process.exit(2);
+  }
+
+  console.log(nextFreeVersion(local, takenVersions(fetchPackument(name))));
+}

package/template/scripts/pin-workspace-deps.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * Rewrite `workspace:*` dependency ranges in the *current directory's*
+ * package.json to real semver ranges, immediately before `npm publish` packs it.
+ *
+ * npm keeps the literal `workspace:*` protocol in the published tarball, and no
+ * consumer outside this monorepo can resolve it — `npm install` of such a
+ * package dies with EUNSUPPORTEDPROTOCOL. Every workspace has to substitute
+ * real ranges at pack time; this is that substitution.
+ *
+ * A `workspace:*` dependency on a local package that is private (and so never
+ * published) is dropped rather than pinned: pinning it would produce a tarball
+ * that cannot install at all.
+ *
+ * The edit is deliberately left in the working tree — `restore-pinned-deps.mjs`
+ * takes it back out after the publish, keeping only any version bump.
+ *
+ * Usage: node scripts/pin-workspace-deps.mjs [packageDir] [workspaceRoot]
+ *   Both default to what the publish loop needs: the current directory, and its
+ *   parent as the directory holding sibling packages.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+
+/**
+ * Map local package name -> { version, private } for every sibling.
+ *
+ * @param {string} siblingsRoot directory containing the package directories
+ * @returns {Map<string, { version: string, private: boolean }>}
+ */
+export function readSiblings(siblingsRoot) {
+  const siblings = new Map();
+  if (!fs.existsSync(siblingsRoot)) return siblings;
+
+  for (const entry of fs.readdirSync(siblingsRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+
+    const manifestPath = path.join(siblingsRoot, entry.name, 'package.json');
+    if (!fs.existsSync(manifestPath)) continue;
+
+    try {
+      const pkg = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+      if (pkg.name && pkg.version) {
+        siblings.set(pkg.name, { version: pkg.version, private: Boolean(pkg.private) });
+      }
+    } catch {
+      // A sibling with an unreadable manifest simply cannot be pinned against.
+    }
+  }
+
+  return siblings;
+}
+
+/**
+ * Substitute every `workspace:` range in `pkg`, in place.
+ *
+ * @param {Record<string, any>} pkg parsed package.json, mutated
+ * @param {Map<string, { version: string, private: boolean }>} siblings
+ * @returns {string[]} human-readable log lines describing what changed
+ */
+export function pinWorkspaceDeps(pkg, siblings) {
+  const changes = [];
+
+  for (const field of DEPENDENCY_FIELDS) {
+    const deps = pkg[field];
+    if (!deps) continue;
+
+    for (const [name, range] of Object.entries(deps)) {
+      if (typeof range !== 'string' || !range.startsWith('workspace:')) continue;
+
+      const sibling = siblings.get(name);
+
+      if (!sibling || sibling.private) {
+        delete deps[name];
+        changes.push(`Removed unpublishable workspace dependency: ${name}`);
+        continue;
+      }
+
+      // `workspace:1.2.3` and `workspace:^1.2.3` already carry the range the
+      // author wants; only the `*`/`~`/`^` shorthands need the local version.
+      const suffix = range.slice('workspace:'.length);
+      deps[name] = /^[\d]/.test(suffix) || /^[~^][\d]/.test(suffix)
+        ? suffix
+        : `^${sibling.version}`;
+      changes.push(`Pinned workspace dependency ${name} -> ${deps[name]}`);
+    }
+  }
+
+  return changes;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  const packageDir = process.argv[2] ?? '.';
+  const siblingsRoot = process.argv[3] ?? path.join(packageDir, '..');
+
+  const manifestPath = path.join(packageDir, 'package.json');
+  const pkg = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+
+  const changes = pinWorkspaceDeps(pkg, readSiblings(siblingsRoot));
+  for (const change of changes) console.log(change);
+
+  if (changes.length > 0) {
+    fs.writeFileSync(manifestPath, `${JSON.stringify(pkg, null, 2)}\n`);
+  }
+}

package/template/scripts/restore-pinned-deps.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * Undo `pin-workspace-deps.mjs` across the workspace, keeping only the version
+ * bumps that the publish step made.
+ *
+ * After a publish run, each published package's package.json holds two kinds of
+ * edit: a `version` bump, which must be committed so the next run does not
+ * re-derive it, and the `workspace:*` -> `^x.y.z` pinning, which must not —
+ * committing that would freeze siblings at whatever version they happened to
+ * have and break local development.
+ *
+ * Restoring each file from `git show HEAD:` and patching only the version
+ * string back in keeps the committed diff to one line per bumped package, and
+ * keeps each file's original formatting.
+ *
+ * Usage: node scripts/restore-pinned-deps.mjs [packagesRoot...]
+ *   Defaults to `packages`.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * Put `version` back into the *original* file text, leaving everything else as
+ * it was committed.
+ *
+ * A string replace rather than parse/serialize: reserializing would reformat
+ * files that use different indentation or key order, turning a one-line version
+ * bump into a whole-file diff.
+ *
+ * @param {string} original the committed file text
+ * @param {string} fromVersion version in the committed text
+ * @param {string} toVersion version to restore
+ * @returns {string}
+ */
+export function patchVersion(original, fromVersion, toVersion) {
+  if (fromVersion === toVersion) return original;
+
+  const needle = `"version": "${fromVersion}"`;
+  if (original.includes(needle)) {
+    return original.replace(needle, `"version": "${toVersion}"`);
+  }
+
+  // Different spacing around the colon (e.g. 4-space or minified manifests).
+  return original.replace(
+    new RegExp(`("version"\\s*:\\s*)"${fromVersion.replace(/\./g, '\\.')}"`),
+    `$1"${toVersion}"`,
+  );
+}
+
+/**
+ * @param {string[]} roots directories containing package directories
+ * @param {(file: string) => string} [showHead] injection point for tests
+ * @returns {string[]} log lines
+ */
+export function restore(roots, showHead = defaultShowHead) {
+  const messages = [];
+
+  for (const root of roots) {
+    if (!fs.existsSync(root)) continue;
+
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+
+      const file = path.join(root, entry.name, 'package.json');
+      if (!fs.existsSync(file)) continue;
+
+      let committed;
+      try {
+        committed = showHead(file);
+      } catch {
+        // Untracked package: there is no committed text to restore it to, and
+        // its whole manifest is new, so leave it exactly as it is.
+        continue;
+      }
+
+      const current = JSON.parse(fs.readFileSync(file, 'utf8'));
+      const original = JSON.parse(committed);
+
+      if (original.version !== current.version) {
+        messages.push(`Keeping version bump for ${current.name} -> ${current.version}`);
+      }
+
+      fs.writeFileSync(file, patchVersion(committed, original.version, current.version));
+    }
+  }
+
+  return messages;
+}
+
+function defaultShowHead(file) {
+  return execFileSync('git', ['show', `HEAD:${file}`], { encoding: 'utf8' });
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  const roots = process.argv.slice(2);
+  for (const message of restore(roots.length > 0 ? roots : ['packages'])) {
+    console.log(message);
+  }
+}

package/template/scripts/workspace-build-order.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * Order the workspace's package directories so that every package comes after
+ * each sibling it depends on.
+ *
+ * The npm publish workflow used to walk `packages/*​/`, i.e. shell-glob
+ * (alphabetical) order, which has nothing to do with the dependency graph.
+ * `bun install` links workspace packages into `node_modules` as symlinks, so a
+ * sibling that has not been built yet has no `dist/` and the `exports` ->
+ * `types` entries in its package.json point at files that do not exist. That
+ * makes any package fail its declaration build on every sibling it depends on
+ * that happens to sort after it:
+ *
+ *   Cannot find module '<sibling>' or its corresponding type declarations.
+ *
+ * Usage: node scripts/workspace-build-order.mjs [rootDir]
+ *   rootDir defaults to `packages`. Prints one directory per line, with a
+ *   trailing slash, e.g. `packages/my-lib/`.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * Read every `<root>/<dir>/package.json` that exists.
+ *
+ * @param {string} root
+ * @returns {{ dir: string, pkg: Record<string, any> }[]}
+ */
+export function readWorkspacePackages(root) {
+  const packages = [];
+
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+
+    const manifest = path.join(root, entry.name, 'package.json');
+    if (!fs.existsSync(manifest)) continue;
+
+    let pkg;
+    try {
+      pkg = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+    } catch (error) {
+      console.error(`Skipping ${manifest}: ${error.message}`);
+      continue;
+    }
+    if (!pkg.name) continue;
+
+    packages.push({ dir: entry.name, pkg });
+  }
+
+  return packages;
+}
+
+/**
+ * Map each package directory to the sibling directories it depends on.
+ *
+ * Local edges are keyed by package *name*, not by the version range: bun links
+ * a sibling into node_modules whenever the name matches a workspace package, so
+ * `"<sibling>": "^0.1.37"` resolves to the local copy exactly like
+ * `"workspace:*"` does, and needs building just the same.
+ *
+ * @param {{ dir: string, pkg: Record<string, any> }[]} packages
+ * @returns {Map<string, Set<string>>}
+ */
+export function localDependencyGraph(packages) {
+  const dirByName = new Map(packages.map(({ dir, pkg }) => [pkg.name, dir]));
+  const graph = new Map();
+
+  for (const { dir, pkg } of packages) {
+    const local = new Set();
+    for (const field of [
+      'dependencies',
+      'devDependencies',
+      'peerDependencies',
+      'optionalDependencies',
+    ]) {
+      for (const name of Object.keys(pkg[field] ?? {})) {
+        const depDir = dirByName.get(name);
+        if (depDir && depDir !== dir) local.add(depDir);
+      }
+    }
+    graph.set(dir, local);
+  }
+
+  return graph;
+}
+
+/**
+ * Topologically sort the workspace, alphabetically within each ready set so the
+ * order is stable across runs and stays close to the old one where the graph
+ * allows it.
+ *
+ * @param {string} [root]
+ * @returns {string[]} directories, e.g. `['packages/my-lib/', ...]`
+ */
+export function workspaceBuildOrder(root = 'packages') {
+  const packages = readWorkspacePackages(root);
+  const dependencies = localDependencyGraph(packages);
+
+  const pending = packages.map(({ dir }) => dir).sort();
+  const built = new Set();
+  const order = [];
+
+  while (pending.length > 0) {
+    const ready = pending.findIndex((dir) =>
+      [...dependencies.get(dir)].every((dep) => built.has(dep)),
+    );
+
+    // A dependency cycle leaves nothing ready. No order can be right, so take
+    // the alphabetically first entry and keep going: everything still gets
+    // built and published, and the cycle is reported on stderr where it shows
+    // up in the job log.
+    if (ready === -1) {
+      console.error(
+        `Dependency cycle involving ${pending[0]} — falling back to alphabetical order for it`,
+      );
+    }
+
+    const [dir] = pending.splice(ready === -1 ? 0 : ready, 1);
+    built.add(dir);
+    order.push(`${root}/${dir}/`);
+  }
+
+  return order;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  console.log(workspaceBuildOrder(process.argv[2]).join('\n'));
+}