setup-git-repo 1.0.1 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "setup-git-repo",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "One command to set up a GitHub repo: Turborepo, CI workflows, README badges, and the docs for each",
   "type": "module",
   "bin": {
@@ -43,6 +43,7 @@
   "homepage": "https://github.com/OpenSourceAGI/dev-tools-starter-agent/tree/master/packages/setup-git-repo",
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.0",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.0",
+    "yaml": "^2.9.0"
   }
 }

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

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * Emit the test matrix for `.github/workflows/tests.yml`.
+ *
+ * This was an inline `node --input-type=module -e '...'` in the workflow. Moved
+ * out for two reasons: an inline heredoc cannot be unit tested, and the inline
+ * version hardcoded `["packages", "apps"]` as the places to look. A repo whose
+ * workspaces are `libs/*` got an empty matrix and no error — the failure mode
+ * of the hand-maintained matrix this was meant to replace.
+ *
+ * The workspace globs from the root package.json are the source of truth now.
+ *
+ *   node .github/scripts/list-test-packages.mjs [rootDir]
+ *
+ * Writes `packages=<json>` and `any=<bool>` to $GITHUB_OUTPUT (or stdout when
+ * that is unset, which is what the tests read).
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { basename, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** The script a package must define to be picked up, best first. */
+const TEST_SCRIPTS = ["test:ci", "test:coverage", "test"];
+
+/** Read and parse a JSON file, treating any failure as absent. */
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Expand the root package.json `workspaces` field into directories.
+ *
+ * Only a trailing `/*` is expanded — anything cleverer would need a glob
+ * dependency in a script that runs before `install`. Both the array and the
+ * `{ packages: [] }` object forms are accepted, because npm and bun both do.
+ *
+ * Falls back to `packages` and `apps` so a repo with no workspaces field
+ * behaves as it did before this script existed.
+ *
+ * @param {string} [root]
+ * @returns {string[]} directories relative to the repo root
+ */
+export function workspaceDirectories(root = ".") {
+  const manifest = readJson(join(root, "package.json"));
+  const globs = Array.isArray(manifest?.workspaces)
+    ? manifest.workspaces
+    : (manifest?.workspaces?.packages ?? ["packages/*", "apps/*"]);
+
+  const directories = [];
+
+  for (const glob of globs) {
+    if (!glob.endsWith("/*")) {
+      if (existsSync(join(root, glob))) directories.push(glob);
+      continue;
+    }
+
+    const parent = glob.slice(0, -2);
+    if (!existsSync(join(root, parent))) continue;
+
+    for (const entry of readdirSync(join(root, parent), { withFileTypes: true })) {
+      if (entry.isDirectory()) directories.push(`${parent}/${entry.name}`);
+    }
+  }
+
+  return directories.sort();
+}
+
+/**
+ * Every workspace package that declares a test script.
+ *
+ * @param {string} [root]
+ * @returns {{ name: string, dir: string, flag: string, script: string }[]}
+ */
+export function testPackages(root = ".") {
+  const found = [];
+
+  for (const dir of workspaceDirectories(root)) {
+    const pkg = readJson(join(root, dir, "package.json"));
+    if (!pkg) continue;
+
+    const script = TEST_SCRIPTS.find((candidate) => pkg.scripts?.[candidate]);
+    if (!script) continue;
+
+    found.push({
+      name: pkg.name ?? basename(dir),
+      dir,
+      // The Codecov flag is the directory name, which is what someone reading
+      // the Codecov dashboard is looking for.
+      flag: basename(dir),
+      script,
+    });
+  }
+
+  return found;
+}
+
+/**
+ * @param {ReturnType<typeof testPackages>} packages
+ * @returns {string} the $GITHUB_OUTPUT lines
+ */
+export function formatOutput(packages) {
+  // `any` exists because GitHub fails a job whose matrix is empty, which would
+  // make a repo with no suites look broken rather than untested.
+  return `packages=${JSON.stringify(packages)}\nany=${packages.length > 0}\n`;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  const packages = testPackages(process.argv[2]);
+
+  console.log(
+    packages.length > 0
+      ? packages.map((p) => `${p.dir} (${p.script})`).join("\n")
+      : "No workspace package defines a test script.",
+  );
+
+  const output = formatOutput(packages);
+  if (process.env.GITHUB_OUTPUT) {
+    const { appendFileSync } = await import("node:fs");
+    appendFileSync(process.env.GITHUB_OUTPUT, output);
+  } else {
+    process.stdout.write(output);
+  }
+}

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

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+/**
+ * Rewrite `workspace:*` 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 the monorepo can resolve it — installing such a package dies
+ * with EUNSUPPORTEDPROTOCOL. Every workspace has to substitute real ranges at
+ * pack time; this is that substitution, moved out of the inline `node -e` it
+ * used to be so it can be tested.
+ *
+ * A dependency on a local package that is private (and so never published) is
+ * dropped rather than pinned: pinning it produces a tarball that cannot install
+ * at all.
+ *
+ * The edit is left in the working tree on purpose — `restore-pinned-deps.mjs`
+ * takes it back out after the publish, keeping only any version bump.
+ *
+ *   node .github/scripts/pin-workspace-deps.mjs [packageDir] [siblingsRoot...]
+ */
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const DEPENDENCY_FIELDS = ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];
+
+/**
+ * Map local package name -> { version, private } across the given roots.
+ *
+ * @param {string[]} roots
+ * @returns {Map<string, { version: string, private: boolean }>}
+ */
+export function readSiblings(roots) {
+  const siblings = new Map();
+
+  for (const root of roots) {
+    if (!existsSync(root)) continue;
+
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+
+      const manifest = join(root, entry.name, "package.json");
+      if (!existsSync(manifest)) continue;
+
+      try {
+        const pkg = JSON.parse(readFileSync(manifest, "utf8"));
+        if (pkg.name && pkg.version) {
+          siblings.set(pkg.name, { version: pkg.version, private: Boolean(pkg.private) });
+        }
+      } catch {
+        // A sibling with an unreadable manifest 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[]} 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 chose; only the `*`, `~` and `^` shorthands need the local
+      // version substituted in.
+      const suffix = range.slice("workspace:".length);
+      deps[name] = /^[~^]?\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 = ".", ...rootArgs] = process.argv.slice(2);
+  // Default roots are the publish workflow's: siblings live one level up from
+  // the package being published.
+  const roots = rootArgs.length > 0 ? rootArgs : [join(packageDir, "..")];
+
+  const manifestPath = join(packageDir, "package.json");
+  const pkg = JSON.parse(readFileSync(manifestPath, "utf8"));
+
+  const changes = pinWorkspaceDeps(pkg, readSiblings(roots));
+  for (const change of changes) console.log(change);
+
+  if (changes.length > 0) writeFileSync(manifestPath, `${JSON.stringify(pkg, null, 2)}\n`);
+}

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

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * Undo `pin-workspace-deps.mjs` across the workspace, keeping only the version
+ * bumps the publish step made.
+ *
+ * After a publish run each published 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 back
+ * in keeps the committed diff to one line per bumped package, and keeps each
+ * file's original formatting.
+ *
+ * This replaces an inline `node -e` that matched the literal string
+ * `"version": "<old>"`. A package.json without the space after the colon — or
+ * with tab indentation — silently kept its pinned dependencies and lost its
+ * bump, while logging that it had kept it. The rewrite is now verified: a patch
+ * that matches nothing is an error, not a silent no-op.
+ *
+ *   node .github/scripts/restore-pinned-deps.mjs [packagesRoot...]
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * Put `toVersion` back into the committed file text, leaving all else as it was
+ * committed.
+ *
+ * A targeted replace rather than parse-and-reserialize: 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}
+ * @throws if the version field could not be found
+ */
+export function patchVersion(original, fromVersion, toVersion) {
+  if (fromVersion === toVersion) return original;
+
+  const pattern = new RegExp(`("version"\\s*:\\s*)"${fromVersion.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}"`);
+  const patched = original.replace(pattern, `$1"${toVersion}"`);
+
+  if (patched === original) {
+    throw new Error(`could not find "version": "${fromVersion}" to replace with "${toVersion}"`);
+  }
+
+  return patched;
+}
+
+/**
+ * One package whose version field cannot be rewritten must not abort the loop
+ * and leave every later package still carrying its pinned dependencies, so a
+ * failure is collected and reported rather than thrown.
+ *
+ * @param {string[]} roots
+ * @param {(file: string) => string} [showHead] injection point for tests
+ * @returns {{ messages: string[], failures: string[] }}
+ */
+export function restore(roots, showHead = defaultShowHead) {
+  const messages = [];
+  const failures = [];
+
+  for (const root of roots) {
+    if (!existsSync(root)) continue;
+
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+
+      const file = join(root, entry.name, "package.json");
+      if (!existsSync(file)) continue;
+
+      let committed;
+      try {
+        committed = showHead(file);
+      } catch {
+        // An untracked package has no committed text to restore to, and its
+        // whole manifest is new — leave it exactly as it is.
+        continue;
+      }
+
+      const current = JSON.parse(readFileSync(file, "utf8"));
+      const original = JSON.parse(committed);
+
+      let restored;
+      try {
+        restored = patchVersion(committed, original.version, current.version);
+      } catch {
+        // The package was published under the new version; if the repo keeps
+        // the old one, the next run republishes the same content forever.
+        failures.push(
+          `::error title=Version bump lost::Could not rewrite the version field in ${file}. ` +
+            `${current.name} was published as ${current.version} but the repo still says ${original.version}.`,
+        );
+        continue;
+      }
+
+      if (original.version !== current.version) {
+        messages.push(`Keeping version bump for ${current.name} -> ${current.version}`);
+      }
+
+      writeFileSync(file, restored);
+    }
+  }
+
+  return { messages, failures };
+}
+
+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);
+  const { messages, failures } = restore(roots.length > 0 ? roots : ["packages", "apps"]);
+
+  for (const message of messages) console.log(message);
+  for (const failure of failures) console.log(failure);
+
+  if (failures.length > 0) process.exitCode = 1;
+}

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

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * Order the workspace's package directories so every package comes after each
+ * sibling it depends on.
+ *
+ * The publish workflow used to walk `packages/*​/ apps/*​/`, i.e. shell-glob
+ * (alphabetical) order, which has nothing to do with the dependency graph. Bun
+ * and pnpm link workspace siblings 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. The
+ * package that sorts earlier then fails its declaration build with:
+ *
+ *   Cannot find module '<sibling>' or its corresponding type declarations.
+ *
+ * Dependency order also means a sibling's `workspace:*` pin is rewritten to the
+ * version that sibling just published, rather than the one it had before its
+ * own bump.
+ *
+ *   node .github/scripts/workspace-build-order.mjs [rootDir...]
+ *
+ * Prints one directory per line with a trailing slash, e.g. `packages/core/`.
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const DEPENDENCY_FIELDS = ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];
+
+/**
+ * Read every `<root>/<dir>/package.json` across the given roots.
+ *
+ * @param {string[]} roots
+ * @returns {{ dir: string, pkg: Record<string, any> }[]}
+ */
+export function readWorkspacePackages(roots) {
+  const packages = [];
+
+  for (const root of roots) {
+    if (!existsSync(root)) continue;
+
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+
+      const manifest = join(root, entry.name, "package.json");
+      if (!existsSync(manifest)) continue;
+
+      try {
+        const pkg = JSON.parse(readFileSync(manifest, "utf8"));
+        if (pkg.name) packages.push({ dir: `${root}/${entry.name}`, pkg });
+      } catch (error) {
+        console.error(`Skipping ${manifest}: ${error.message}`);
+      }
+    }
+  }
+
+  return packages;
+}
+
+/**
+ * Map each package directory to the sibling directories it depends on.
+ *
+ * Edges are keyed by package *name*, not by the version range: a workspace
+ * sibling is linked whenever the name matches, so `"core": "^1.2.3"` resolves
+ * to the local copy exactly as `"workspace:*"` does and needs building just the
+ * same.
+ *
+ * @param {ReturnType<typeof readWorkspacePackages>} 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 DEPENDENCY_FIELDS) {
+      for (const name of Object.keys(pkg[field] ?? {})) {
+        const dependency = dirByName.get(name);
+        if (dependency && dependency !== dir) local.add(dependency);
+      }
+    }
+
+    graph.set(dir, local);
+  }
+
+  return graph;
+}
+
+/**
+ * Topologically sort the workspace, alphabetically within each ready set so the
+ * order is stable across runs.
+ *
+ * @param {string[]} [roots]
+ * @returns {string[]} directories with a trailing slash
+ */
+export function workspaceBuildOrder(roots = ["packages", "apps"]) {
+  const packages = readWorkspacePackages(roots);
+  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 lands
+    // 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(`${dir}/`);
+  }
+
+  return order;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  const roots = process.argv.slice(2);
+  console.log(workspaceBuildOrder(roots.length > 0 ? roots : undefined).join("\n"));
+}

package/template/.github/workflows/deploy-test-reports.yml

@@ -7,6 +7,13 @@ on:
     branches: [{{DEFAULT_BRANCH}}]
   workflow_dispatch:
 
+# Two pushes in quick succession would otherwise race `wrangler deploy`, and the
+# report that wins is whichever upload finishes last, not whichever commit is
+# newer. Cancel the older run instead.
+concurrency:
+  group: test-reports
+  cancel-in-progress: true
+
 jobs:
   deploy:
     name: Generate & Deploy Test Reports

package/template/.github/workflows/npm-publish.yml

@@ -166,7 +166,14 @@ jobs:
           unattempted_packages=""
           auth_broken=""
 
-          for dir in packages/*/ apps/*/; do
+          # Dependency order, not shell-glob (alphabetical) order: a sibling
+          # that has not been built yet has no dist/, so a package that sorts
+          # earlier fails its declaration build on every sibling it imports.
+          build_order=$(node "$GITHUB_WORKSPACE/.github/scripts/workspace-build-order.mjs" packages apps)
+          echo "📋 Build order:"
+          echo "$build_order" | sed 's/^/   /'
+
+          for dir in $build_order; do
             pkg="${dir}package.json"
             [ -f "$pkg" ] || continue
 
@@ -201,37 +208,7 @@ jobs:
               # semver range taken from the referenced local package; drop
               # local packages that are not published. Only the version field
               # of this edit is committed back, in the final step.
-              node -e "
-                const fs = require('fs');
-                const path = require('path');
-                const localVersions = {};
-                for (const root of ['../../packages', '../../apps']) {
-                  if (!fs.existsSync(root)) continue;
-                  for (const d of fs.readdirSync(root)) {
-                    const sib = path.join(root, d, 'package.json');
-                    if (!fs.existsSync(sib)) continue;
-                    try {
-                      const sp = JSON.parse(fs.readFileSync(sib, 'utf8'));
-                      if (sp.name && sp.version && !sp.private) localVersions[sp.name] = sp.version;
-                    } catch {}
-                  }
-                }
-                const p = JSON.parse(fs.readFileSync('package.json', 'utf8'));
-                for (const s of ['dependencies', 'devDependencies', 'peerDependencies']) {
-                  if (!p[s]) continue;
-                  for (const [k, v] of Object.entries(p[s])) {
-                    if (typeof v !== 'string' || !v.startsWith('workspace:')) continue;
-                    if (localVersions[k]) {
-                      p[s][k] = '^' + localVersions[k];
-                      console.log('Pinned workspace dependency', k, '->', p[s][k]);
-                    } else {
-                      delete p[s][k];
-                      console.log('Removed unresolved workspace dependency:', k);
-                    }
-                  }
-                }
-                fs.writeFileSync('package.json', JSON.stringify(p, null, 2));
-              "
+              node "$GITHUB_WORKSPACE/.github/scripts/pin-workspace-deps.mjs" . ../../packages ../../apps
 
               version=$(node -e "const p=require('./package.json'); console.log(p.version)")
               latest=$(npm view "$name" version 2>/dev/null || echo "")
@@ -351,42 +328,7 @@ jobs:
           # Version bumps made during publish must land back in the repo so the
           # next run sees them. Restore the workspace:* pinning done for the
           # tarballs first — only the "version" field should be committed.
-          node -e "
-            const fs = require('fs');
-            const cp = require('child_process');
-            for (const root of ['packages', 'apps']) {
-              if (!fs.existsSync(root)) continue;
-              for (const d of fs.readdirSync(root)) {
-                const f = root + '/' + d + '/package.json';
-                if (!fs.existsSync(f)) continue;
-                const now = JSON.parse(fs.readFileSync(f, 'utf8'));
-                let raw;
-                try {
-                  raw = cp.execSync('git show HEAD:' + f, { encoding: 'utf8' });
-                } catch { continue; }
-                const orig = JSON.parse(raw);
-                if (orig.version !== now.version) {
-                  // Patch only the version string so the file keeps whatever
-                  // formatting it had. Matching on a literal '\"version\": \"x\"'
-                  // would miss a package.json written without the space after
-                  // the colon, and silently drop the bump while claiming to
-                  // keep it — so match the field, then assert it changed.
-                  const before = raw;
-                  raw = raw.replace(
-                    /(\"version\"\s*:\s*\")[^\"]*(\")/,
-                    (m, open_, close) => open_ + now.version + close
-                  );
-                  if (raw === before) {
-                    console.log('::error title=Version bump lost::Could not rewrite the version field in ' + f + '. ' + now.name + ' was published as ' + now.version + ' but the repo still says ' + orig.version + '.');
-                    process.exitCode = 1;
-                    continue;
-                  }
-                  console.log('Keeping version bump for', now.name, '->', now.version);
-                }
-                fs.writeFileSync(f, raw);
-              }
-            }
-          "
+          node .github/scripts/restore-pinned-deps.mjs packages apps
           git add packages/*/package.json apps/*/package.json 2>/dev/null || true
           git diff --staged --quiet && echo "No version changes to commit" && exit 0
           # [skip ci] so the bump commit does not retrigger this workflow.

package/template/.github/workflows/tests.yml

@@ -3,8 +3,10 @@
 # per test and comments the failing ones on the pull request.
 #
 # The matrix is discovered at run time rather than hand-maintained: adding a
-# package with a `test:ci` script is all it takes to get it tested here. That
-# script must write, relative to the package directory:
+# package with a `test:ci` script is all it takes to get it tested here. The
+# packages searched come from the root package.json `workspaces` globs, so a
+# repo laid out as `libs/*` is covered without editing this file. That script
+# must write, relative to the package directory:
 #
 #   junit.xml         - test results, the input Test Analytics ingests
 #   coverage/lcov.info - coverage, uploaded when the runner can produce it
@@ -36,27 +38,8 @@ jobs:
       - uses: actions/checkout@v4
 
       - id: list
-        name: Find packages with a test:ci script
-        run: |
-          node --input-type=module -e '
-            import { readdirSync, readFileSync, existsSync, appendFileSync } from "node:fs";
-            const out = [];
-            for (const root of ["packages", "apps"]) {
-              if (!existsSync(root)) continue;
-              for (const dir of readdirSync(root)) {
-                const file = `${root}/${dir}/package.json`;
-                if (!existsSync(file)) continue;
-                let pkg;
-                try { pkg = JSON.parse(readFileSync(file, "utf8")); } catch { continue; }
-                if (!pkg.scripts?.["test:ci"]) continue;
-                out.push({ name: pkg.name ?? dir, dir: `${root}/${dir}` });
-              }
-            }
-            out.sort((a, b) => a.dir.localeCompare(b.dir));
-            appendFileSync(process.env.GITHUB_OUTPUT, `packages=${JSON.stringify(out)}\n`);
-            appendFileSync(process.env.GITHUB_OUTPUT, `any=${out.length > 0}\n`);
-            console.log(out.length ? out.map((p) => p.dir).join("\n") : "No package defines a test:ci script.");
-          '
+        name: Find packages with a test script
+        run: node .github/scripts/list-test-packages.mjs
 
   test:
     needs: discover
@@ -85,7 +68,7 @@ jobs:
       # `turbo run` builds this package's workspace dependencies first, so a
       # package that imports a sibling through its built `dist` output finds it.
       - name: Run tests
-        run: bunx turbo run test:ci --filter=./${{ matrix.package.dir }}
+        run: bunx turbo run ${{ matrix.package.script }} --filter=./${{ matrix.package.dir }}
 
       # `!cancelled()` so a red suite still reports: without it the upload is
       # skipped on exactly the runs whose results matter most.

package/template/docs/WORKFLOWS.md

@@ -16,7 +16,7 @@ the part that costs hours if you meet them cold.
 
 ## tests.yml
 
-Discovers every workspace package with a `test:ci` script, runs each as its own
+Discovers every workspace package with a test script, runs each as its own
 matrix job, and uploads results to Codecov Test Analytics and coverage to
 Codecov.
 
@@ -26,6 +26,12 @@ workflow — the package silently has no CI. A `discover` job emits the list as
 JSON; the `test` job consumes it through `fromJSON`. GitHub cannot compute a
 matrix inside the job that uses it, which is why it is two jobs.
 
+**Where it looks.** `.github/scripts/list-test-packages.mjs` expands the root
+package.json `workspaces` globs, so a repo laid out as `libs/*` is covered with
+no edit here. It prefers `test:ci`, falling back to `test:coverage` and then
+`test`, and the job runs whichever it found — a package with only a plain `test`
+script is tested rather than skipped.
+
 **What your package must produce.** Relative to the package directory:
 
 ```
@@ -56,7 +62,7 @@ For Vitest:
 
 | Symptom | Cause → fix |
 | --- | --- |
-| A package you added never appears as a job | It has no `test:ci` script, or it lives outside `packages/`, `apps/` |
+| A package you added never appears as a job | It has no `test:ci`, `test:coverage` or `test` script, or it lives outside the root package.json `workspaces` globs |
 | `Error: Unable to process file command 'output'` in `discover` | A package name contains a newline or the JSON exceeded the 1MB output cap |
 | Codecov shows the run but no coverage | The runner wrote no `lcov.info` — `--coverage` missing, or a provider that writes nothing on your Node version |
 | Coverage drops to 0% for an untouched package | `carryforward` is off for that flag in `codecov.yml` |
@@ -93,6 +99,14 @@ provenance statement into the public sigstore transparency log.
 
 **Details that matter:**
 
+- Packages are walked in dependency order, from
+  `.github/scripts/workspace-build-order.mjs`, not in shell-glob (alphabetical)
+  order. Workspace siblings are symlinked into `node_modules`, so one that has
+  not been built yet has no `dist/` and its package.json `types` entries point
+  at files that do not exist — the package that sorts earlier fails its
+  declaration build with `Cannot find module '<sibling>'`. Dependency order also
+  means a sibling's `workspace:*` pin is rewritten to the version that sibling
+  just published, not the one it had before its own bump.
 - `set +e` in the publish loop. GitHub runs `run:` steps with `bash -e -o
   pipefail`, so *not* writing `set -e` does not disable errexit — the first
   failing package would kill the step and leave every later package unevaluated.
@@ -100,21 +114,27 @@ provenance statement into the public sigstore transparency log.
 - Exit 43 means "npm rejected the credential". The loop stops attempting further
   packages: they would all fail the same way, after another build and another
   provenance signature each.
-- `workspace:*` dependencies are rewritten to real semver ranges before packing.
-  npm keeps the literal protocol in the tarball, and consumers cannot resolve it.
-  Only the `version` field of that edit is committed back.
+- `workspace:*` dependencies are rewritten to real semver ranges before packing
+  (`.github/scripts/pin-workspace-deps.mjs`). npm keeps the literal protocol in
+  the tarball, and consumers cannot resolve it. A dependency on a *private*
+  sibling is dropped rather than pinned — pinning it produces a tarball that
+  cannot install at all. An explicit `workspace:^1.0.0` keeps the range its
+  author chose. Only the `version` field of that edit is committed back.
 - A local version *behind* the registry is synced forward first, otherwise the
   publish fails with "Cannot implicitly apply the latest tag".
 - `E409 cannot publish over previously staged version` is retried at the next
   free version, up to five times. `latest` lags versions an interrupted publish
   reserved; `.github/scripts/next-free-version.mjs` reads the full version list
   *and* the release timeline, which is where those numbers appear.
-- The final step rewrites only the `version` field back into each
-  `package.json`, by regex rather than by re-serializing the parsed object, so
-  the file keeps its own formatting. It matches `"version"\s*:\s*"..."` rather
-  than a literal `"version": "x"`, and fails the step if the replace found
-  nothing — a package.json written without the space after the colon would
-  otherwise silently lose the bump while the log claimed to keep it.
+- The final step (`.github/scripts/restore-pinned-deps.mjs`) rewrites only the
+  `version` field back into each `package.json`, by regex rather than by
+  re-serializing the parsed object, so the file keeps its own formatting. It
+  matches `"version"\s*:\s*"..."` rather than a literal `"version": "x"`, and
+  reports a failure if the replace found nothing — a package.json written
+  without the space after the colon would otherwise silently lose the bump while
+  the log claimed to keep it. One unrewritable file is reported and the step
+  fails at the end, rather than aborting the loop and leaving every later
+  package still carrying its pinned dependencies.
 - The bump commit ends in `[skip ci]` so it does not retrigger the workflow.
 - A no-op `husky` is put on PATH. Some published dependencies ship
   `prepare: "husky install"`; when npm reconciles bun's linked `node_modules` it
@@ -203,3 +223,27 @@ it fetches them into an empty workspace rather than paying for a full checkout.
 - **`main` instead of `master`.** Every `branches:` filter in this template is
   written by `setup-git-repo` from your repo's actual default branch. If you
   rename the branch later, grep the workflows for the old name.
+
+## .github/scripts/
+
+The workflows' logic lives here rather than in inline `node -e` heredocs, so it
+can be unit tested — these run in *your* CI with nobody watching, and a bug in
+one surfaces as a failed workflow rather than a failed test. They are covered by
+`packages/setup-git-repo/test/template-scripts.test.mjs` in the repo this
+template comes from.
+
+| Script | Called by | Does |
+| --- | --- | --- |
+| `list-test-packages.mjs` | `tests.yml` | Emits the test matrix from the root `workspaces` globs |
+| `workspace-build-order.mjs` | `npm-publish.yml` | Topologically sorts the workspace so a package is built after its siblings |
+| `pin-workspace-deps.mjs` | `npm-publish.yml` | Rewrites `workspace:*` to real ranges at pack time |
+| `next-free-version.mjs` | `npm-publish.yml` | Picks a version the registry has not already spent |
+| `restore-pinned-deps.mjs` | `npm-publish.yml` | Undoes the pinning, keeping only the version bumps |
+
+Each takes its roots as arguments and prints to stdout, so you can run any of
+them locally against your own repo to see what CI will see:
+
+```bash
+node .github/scripts/list-test-packages.mjs
+node .github/scripts/workspace-build-order.mjs packages apps
+```