@monte3l/groundwork 1.0.0-rc.3 → 1.0.0-rc.4

package/dist/main.js

@@ -242,6 +242,27 @@ export function formatCapsSummary(baseline, installed) {
     lines.push(`= ${formatCounts(total)}${overCap.length > 0 ? ` ⚠ over cap: ${overCap.join(", ")}` : ""}`);
     return { text: lines.join("\n"), overCap: overCap.length > 0 };
 }
+/**
+ * Fresh mode's closing "setup required" block: one heading, then each pack
+ * that declares `setupSteps` (in `packs` order) followed by its commands,
+ * each indented two spaces. `undefined` when no pack declares any, so the
+ * caller prints nothing extra.
+ */
+function formatSetupBlock(targetDir, packs) {
+    const lines = [];
+    for (const { manifest } of packs) {
+        const steps = manifest.setupSteps ?? [];
+        if (steps.length === 0)
+            continue;
+        lines.push(`pack "${manifest.name}":`, ...steps.map((step) => `  ${step}`));
+    }
+    if (lines.length === 0)
+        return undefined;
+    return [
+        `\nthe installed pack(s) need setup before the first \`pnpm verify\` -- run these in ${targetDir}:`,
+        ...lines,
+    ].join("\n");
+}
 /**
  * Fresh mode's pre-flight over the `/customize` skill's own destination
  * (`.claude/skills/customize/`): each directory component must be missing
@@ -295,6 +316,18 @@ function runFresh(options, platform) {
             : summary.text);
     }
     const { targetDir, skipInstall, projectName } = options;
+    // Built once, now that the project and its packs are on disk, and printed
+    // exactly once per run: at the very end on success, or just before the
+    // throw when git init / pnpm install fails -- a plain re-run of a
+    // non-empty target adopts it, and adopt mode never prints setupSteps. The
+    // /customize-skill failure below deliberately does not print it: its
+    // message says to re-run with --fresh --force, which prints it on success.
+    const setupBlock = formatSetupBlock(targetDir, packs);
+    const printSetupBlock = () => {
+        if (setupBlock !== undefined) {
+            console.log(paint(process.stdout, "warning", setupBlock));
+        }
+    };
     let pluginResult;
     try {
         pluginResult = installCustomizeSkill(targetDir);
@@ -314,6 +347,7 @@ function runFresh(options, platform) {
         gitInit(targetDir);
     }
     catch (error) {
+        printSetupBlock();
         throw new Error(`git init failed, but the project was written to ${targetDir}; run \`git init\`${skipInstall ? "" : " and `pnpm install`"} there yourself`, { cause: error });
     }
     console.log("initialized git repository");
@@ -323,11 +357,13 @@ function runFresh(options, platform) {
         }
         catch (error) {
             console.log(paint(process.stdout, "warning", `\n${projectName} written to ${targetDir}, but dependencies are not installed`));
+            printSetupBlock();
             throw new Error(`${describeInstallFailure(error)}; the project was written to ${targetDir} -- run \`pnpm install\` there yourself to finish`, { cause: error });
         }
         console.log("installed dependencies");
     }
     console.log(paint(process.stdout, "success", `\n✓ ${projectName} is ready at ${targetDir}`));
+    printSetupBlock();
 }
 /**
  * Explains why the post-emission `pnpm install` failed: a missing binary

package/dist/packs.d.ts

@@ -19,6 +19,8 @@ export interface PackManifest {
     } | undefined;
     wiring: PackWiring;
     adoptNotes: string | undefined;
+    /** Shell commands, run in the target directory, that a fresh install needs before its first `pnpm verify` (fresh mode prints them; see main.ts). Optional: absent means no setup. */
+    setupSteps?: string[] | undefined;
 }
 export interface Pack {
     manifest: PackManifest;
@@ -28,7 +30,7 @@ export interface Pack {
 export declare function packsRootDir(): string;
 /** Names of every pack directory that has a `pack.json` under `root`, sorted for deterministic install order. `root` defaults to `templates/packs`, overridable for tests. */
 export declare function listPackNames(root?: string): string[];
-/** Loads and validates one pack's manifest from under `root` (default `templates/packs`, overridable for tests). Throws, naming the available packs, if unknown; throws naming the pack and the problem if malformed, including a prototype-sensitive key in its wiring (see {@link assertValidWiringShape}). */
+/** Loads and validates one pack's manifest from under `root` (default `templates/packs`, overridable for tests). Throws, naming the available packs, if unknown; throws naming the pack and the problem if malformed, including a prototype-sensitive key in its wiring (see {@link assertValidWiringShape}) or a `setupSteps` that is present but not a non-empty array of single-line, non-empty strings. */
 export declare function loadPack(name: string, root?: string): Pack;
 export interface PackInstallResult {
     filesWritten: string[];

package/dist/packs.js

@@ -132,7 +132,13 @@ function assertValidWiringShape(name, wiring) {
         assertValidVerifyStep(name, step, index);
     });
 }
-/** Loads and validates one pack's manifest from under `root` (default `templates/packs`, overridable for tests). Throws, naming the available packs, if unknown; throws naming the pack and the problem if malformed, including a prototype-sensitive key in its wiring (see {@link assertValidWiringShape}). */
+/** True when `steps` is a non-empty array of non-empty strings, none containing a line break -- each is printed as one indented line. */
+function isValidSetupSteps(steps) {
+    return (Array.isArray(steps) &&
+        steps.length > 0 &&
+        steps.every((step) => typeof step === "string" && step !== "" && !/[\r\n]/.test(step)));
+}
+/** Loads and validates one pack's manifest from under `root` (default `templates/packs`, overridable for tests). Throws, naming the available packs, if unknown; throws naming the pack and the problem if malformed, including a prototype-sensitive key in its wiring (see {@link assertValidWiringShape}) or a `setupSteps` that is present but not a non-empty array of single-line, non-empty strings. */
 export function loadPack(name, root = packsRootDir()) {
     const packDir = join(root, name);
     const manifestPath = join(packDir, "pack.json");
@@ -176,6 +182,10 @@ export function loadPack(name, root = packsRootDir()) {
     if (!isValidBudget(budget)) {
         throw new Error(`pack "${name}": pack.json's budget must set ${CAP_KEYS.join(", ")} to non-negative integers`);
     }
+    const setupSteps = manifest.setupSteps;
+    if (setupSteps !== undefined && !isValidSetupSteps(setupSteps)) {
+        throw new Error(`pack "${name}": pack.json's setupSteps must be a non-empty array of single-line, non-empty strings`);
+    }
     // pack-stage.ts's stagePacks keys each pack's staging directory on
     // manifest.name, so a mismatch would let two pack directories collide.
     if (manifestName !== name) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monte3l/groundwork",
-  "version": "1.0.0-rc.3",
+  "version": "1.0.0-rc.4",
   "description": "CLI that writes a TypeScript toolchain and Claude Code setup into an empty directory, or -- against an existing project -- read-only surveys it and reports the differences. No prompts, and no network access beyond the package install.",
   "keywords": [
     "typescript",

package/templates/packs/README.md

@@ -65,6 +65,15 @@ already enumerate groups rather than individual steps.
 - `wiring.verifySteps` — entries appended to `bin/lib/verify-steps.packs.json`.
 - `adoptNotes` — free text surfaced verbatim in `/customize`'s Step 0
   confirmation round when the pack applies to an adopted project.
+- `setupSteps` — the exact commands a user must run in the new project after
+  the pack is installed and before the first `pnpm verify`, or verify fails
+  (for example, `publishing` needs `@changesets/cli` added, since a pack can
+  never edit `dependencies`). A non-empty array of single-line, non-empty
+  strings; `loadPack` rejects anything else. Fresh mode prints every installed
+  pack's steps in one block after its `ready` line. Adopt mode neither prints
+  them nor adds them to the inventory (the staged `pack.json` still carries the
+  field verbatim): a pack that is adopt-capable and needs setup says so in
+  `adoptNotes`. Optional.
 
 ## Install path
 

package/templates/packs/publishing/files/.github/release-tools/package.json

@@ -4,6 +4,6 @@
   "private": true,
   "description": "Pins the exact npm version the release workflow's publish job installs, so the pin is verified by a committed lockfile's integrity hash rather than a bare version string in YAML.",
   "dependencies": {
-    "npm": "11.20.0"
+    "npm": "12.2.0"
   }
 }

package/templates/packs/publishing/files/.github/workflows/release.yml

@@ -185,12 +185,14 @@ jobs:
           package-manager-cache: false
       # Only the changesets CLI is needed here, not any package's lifecycle scripts.
       - run: pnpm install --frozen-lockfile --ignore-scripts
-      # `npm stage publish` needs npm >= 11.15.0 (Node >= 22.14.0 -- already
-      # covered by .node-version). Pinned to an exact version, not a range or
-      # `latest`: this job holds the OIDC token, and an unpinned
-      # package-manager install is exactly what OpenSSF Scorecard's
-      # Pinned-Dependencies check flags. `.github/release-tools/` pins the
-      # exact tarball via its committed lockfile's integrity hash, and
+      # `npm stage publish` needs npm >= 11.15.0. The pinned npm (12.2.0)
+      # declares engines Node ^22.22.2 || ^24.15.0 || >=26. .node-version's
+      # `24` meets that on GitHub-hosted runners, whose cached 24.x is recent;
+      # a self-hosted runner with an older cached 24.x does not. Pinned to an
+      # exact version, not a range or `latest`: this job holds the OIDC token,
+      # and an unpinned package-manager install is exactly what OpenSSF
+      # Scorecard's Pinned-Dependencies check flags. `.github/release-tools/`
+      # pins the exact tarball via its committed lockfile's integrity hash, and
       # `npm ci` verifies the install against it -- bumping the pin is then
       # a normal reviewed PR (a lockfile diff), not a hand-edited version
       # string.

package/templates/packs/publishing/pack.json

@@ -31,5 +31,11 @@
       }
     ]
   },
-  "adoptNotes": "REQUIRED right after install, before the first pnpm verify -- two one-time steps, or pnpm verify fails immediately, not from a real regression but from two setup gaps this pack cannot close itself: (1) `pnpm add -D @changesets/cli` -- the wiring contract only extends package.json's scripts, never its dependencies (see templates/packs/README.md), so the wired `changeset`/`version:packages` scripts reference a binary knip's own unlisted-binaries check correctly flags as missing until this is installed; (2) `node bin/check-license-headers.mjs --fix`, then commit the result -- templates/core has never had a license-header gate before this pack, so every one of its own files (hooks, bin/ scripts, CI workflows, the placeholder src/tests, and the workflows of any other installed pack such as `github` or `supply-chain`) is missing the SPDX header this pack's own license-headers gate now requires, the same one-time cost this repo itself paid when it adopted the same gate (see CLAUDE.md's Definition of Done). In a hand-copied install the CLI does not substitute tokens, so replace every literal `__PROJECT_NAME__` in the copied files (REUSE.toml, the SPDX headers in bin/, the workflows) with the project's real name first. Fresh mode only: a release pipeline encodes decisions (whether the package is actually public, which registry, whether a GitHub App backs the version PR) this pack cannot survey or guess at safely, so it is staged like every other pack (at .groundwork/packs/publishing/) but never auto-installed in adopt mode -- if an adopted project wants it, copy .groundwork/packs/publishing/files/ by hand, dropping the `.staged` suffix from every name (or copy templates/packs/publishing/files/ from this repo directly) and work through the one-time setup below. check-publish-version.mjs is deliberately NOT one of this pack's wired verify steps: with changesets, package.json's version on the release branch is always the one just published between releases, so a version-already-published check running on every ordinary push (via pnpm verify / pre-push) would fail every single time until the next version PR lands -- it is instead invoked directly as a step inside release.yml's pack job, the one place \"is this version about to collide with an already-published one\" is actually the right question to ask. The two remaining verify-group gates (dts-deps, license-headers) install anywhere a bin/verify.mjs-shaped gate runner exists; wire them into the project's real one if it differs. Both check-publish-version.mjs and check-dts-deps.mjs no-op (checked: 0, not a failure) on a package.json with `private: true` (the baseline's own default) or (check-dts-deps.mjs only) with no dist/**/*.d.ts yet -- flip `private` to `false` (and set a real `name`) once the package is actually meant to publish. The pack assumes a public package: `.changeset/config.json` ships `access: public`, npm refuses `restricted` for an unscoped name, and the publish shim always passes `--provenance`, which npm ties to a public source repository -- a private scoped package needs `access: restricted` and provenance removed from bin/lib/npm-publish-args.mjs. `@changesets/changelog-github` (and its `repo` option) is a drop-in swap for `.changeset/config.json`'s plain default changelog generator, once this project's GitHub repository is known, for changelog entries that link back to the originating PR/commit -- see `.changeset/README.md`. One-time setup before release.yml's first real run (distinct from the two pnpm-verify prerequisites above), distilled from this repo's own .claude/rules/releases.md: (1) npm cannot configure a trusted publisher for a package that doesn't exist yet -- publish once by hand with a temporary token first; (2) the trusted publisher is bound to the exact workflow filename `release.yml` -- renaming or moving it breaks publishing until reconfigured on npmjs.com; (3) set the trusted publisher's allowed actions to staged-only (`npm stage publish`, npm's own default and recommendation since 2026-09-03) -- a maintainer runs `npm stage approve <id>` (2FA, never automatable) before a version actually installs; (4) create an `npm-publish` GitHub environment (via `gh api`, not committed as JSON) with a required reviewer, restricted to the release branch, so the `publish` job itself pauses before the git tag/Release/stage-publish exist; (5) if branch protection requires status checks on every PR with no bypass actor, the version-PR job needs a GitHub App installation token (`APP_CLIENT_ID`/`APP_PRIVATE_KEY` repo secrets), not the default GITHUB_TOKEN, or those checks never trigger and the PR can never merge -- if this project has no such rule, `github-token: ${{ secrets.GITHUB_TOKEN }}` is enough and the app-token step can be dropped. release.yml pins `.github/release-tools/` (the npm CLI version) but the baseline's dependabot.yml only covers the github-actions ecosystem, so that pin goes stale unless you add an `npm` entry with `directory: \"/.github/release-tools\"` to the project's own .github/dependabot.yml. Security note, as of 2026-10-01: the npm pinned in the shipped `.github/release-tools/package-lock.json` (11.20.0) bundles undici 6.28.0, ip-address 10.5.0 and brace-expansion 5.0.9, which carry open advisories; every npm release found that day (11.20.0, 11.21.0, 12.2.0) bundles the same versions, and overrides cannot change bundled dependencies. Reading the npm tarballs and lockfile, no reach was found from what the shipped workflow runs (`npm ci --ignore-scripts`, `npm stage publish <tarball>` and `npm stage list`; the tarball is packed earlier by pnpm, not npm, and the shipped workflow configures no proxy; if your runner sets one, for example HTTPS_PROXY on a self-hosted runner behind an egress proxy, the ip-address advisories may apply), and the minimatch callers on those commands (Arborist, and tuf-js under sigstore) take their patterns from your own lockfile and from signed registry metadata, but that is analysis, not a run of the code. Re-check on the day of each release and bump the pinned npm as soon as a release bundling undici >= 6.28.1, ip-address >= 10.7.1 and brace-expansion >= 5.0.12 exists. The secret-scanning and Scorecard workflows that used to ship here are now the separate `supply-chain` pack."
+  "setupSteps": [
+    "pnpm add -D @changesets/cli",
+    "git add -A",
+    "node bin/check-license-headers.mjs --fix",
+    "git add -A"
+  ],
+  "adoptNotes": "REQUIRED right after install, before the first pnpm verify -- two one-time steps, or pnpm verify fails immediately, not from a real regression but from two setup gaps this pack cannot close itself: (1) `pnpm add -D @changesets/cli` -- the wiring contract only extends package.json's scripts, never its dependencies (see templates/packs/README.md), so the wired `changeset`/`version:packages` scripts reference a binary knip's own unlisted-binaries check correctly flags as missing until this is installed; (2) `git add -A`, then `node bin/check-license-headers.mjs --fix`, then `git add -A` again and commit the result (the gate only checks git-tracked files, so a fresh project with nothing staged passes it vacuously and fails on every file at its first push) -- templates/core has never had a license-header gate before this pack, so every one of its own files (hooks, bin/ scripts, CI workflows, the placeholder src/tests, and the workflows of any other installed pack such as `github` or `supply-chain`) is missing the SPDX header this pack's own license-headers gate now requires, the same one-time cost this repo itself paid when it adopted the same gate (see CLAUDE.md's Definition of Done). In a hand-copied install the CLI does not substitute tokens, so replace every literal `__PROJECT_NAME__` in the copied files (REUSE.toml, the SPDX headers in bin/, the workflows) with the project's real name first. Fresh mode only: a release pipeline encodes decisions (whether the package is actually public, which registry, whether a GitHub App backs the version PR) this pack cannot survey or guess at safely, so it is staged like every other pack (at .groundwork/packs/publishing/) but never auto-installed in adopt mode -- if an adopted project wants it, copy .groundwork/packs/publishing/files/ by hand, dropping the `.staged` suffix from every name (or copy templates/packs/publishing/files/ from this repo directly) and work through the one-time setup below. check-publish-version.mjs is deliberately NOT one of this pack's wired verify steps: with changesets, package.json's version on the release branch is always the one just published between releases, so a version-already-published check running on every ordinary push (via pnpm verify / pre-push) would fail every single time until the next version PR lands -- it is instead invoked directly as a step inside release.yml's pack job, the one place \"is this version about to collide with an already-published one\" is actually the right question to ask. The two remaining verify-group gates (dts-deps, license-headers) install anywhere a bin/verify.mjs-shaped gate runner exists; wire them into the project's real one if it differs. Both check-publish-version.mjs and check-dts-deps.mjs no-op (checked: 0, not a failure) on a package.json with `private: true` (the baseline's own default) or (check-dts-deps.mjs only) with no dist/**/*.d.ts yet -- flip `private` to `false` (and set a real `name`) once the package is actually meant to publish. The pack assumes a public package: `.changeset/config.json` ships `access: public`, npm refuses `restricted` for an unscoped name, and the publish shim always passes `--provenance`, which npm ties to a public source repository -- a private scoped package needs `access: restricted` and provenance removed from bin/lib/npm-publish-args.mjs. `@changesets/changelog-github` (and its `repo` option) is a drop-in swap for `.changeset/config.json`'s plain default changelog generator, once this project's GitHub repository is known, for changelog entries that link back to the originating PR/commit -- see `.changeset/README.md`. One-time setup before release.yml's first real run (distinct from the two pnpm-verify prerequisites above), distilled from this repo's own .claude/rules/releases.md: (1) npm cannot configure a trusted publisher for a package that doesn't exist yet -- publish once by hand with a temporary token first; (2) the trusted publisher is bound to the exact workflow filename `release.yml` -- renaming or moving it breaks publishing until reconfigured on npmjs.com; (3) set the trusted publisher's allowed actions to staged-only (`npm stage publish`, npm's own default and recommendation since 2026-09-03) -- a maintainer runs `npm stage approve <id>` (2FA, never automatable) before a version actually installs; (4) create an `npm-publish` GitHub environment (via `gh api`, not committed as JSON) with a required reviewer, restricted to the release branch, so the `publish` job itself pauses before the git tag/Release/stage-publish exist; (5) if branch protection requires status checks on every PR with no bypass actor, the version-PR job needs a GitHub App installation token (`APP_CLIENT_ID`/`APP_PRIVATE_KEY` repo secrets), not the default GITHUB_TOKEN, or those checks never trigger and the PR can never merge -- if this project has no such rule, `github-token: ${{ secrets.GITHUB_TOKEN }}` is enough and the app-token step can be dropped. release.yml pins `.github/release-tools/` (the npm CLI version) but the baseline's dependabot.yml only covers the github-actions ecosystem, so that pin goes stale unless you add an `npm` entry with `directory: \"/.github/release-tools\"` to the project's own .github/dependabot.yml. Security note, as of 2026-10-01: the npm pinned in the shipped `.github/release-tools/package-lock.json` (12.2.0) bundles undici 6.28.0, ip-address 10.5.0 and brace-expansion 5.0.9, which carry open advisories; every npm release found that day (11.20.0, 11.21.0, 12.2.0) bundles the same versions, and overrides cannot change bundled dependencies. Reading the npm tarballs and lockfile, no reach was found from what the shipped workflow runs (`npm ci --ignore-scripts`, `npm stage publish <tarball>` and `npm stage list`; the tarball is packed earlier by pnpm, not npm, and the shipped workflow configures no proxy; if your runner sets one, for example HTTPS_PROXY on a self-hosted runner behind an egress proxy, the ip-address advisories may apply), and the minimatch callers on those commands (Arborist, and tuf-js under sigstore) take their patterns from your own lockfile and from signed registry metadata, but that is analysis, not a run of the code. Re-check on the day of each release and bump the pinned npm as soon as a release bundling undici >= 6.28.1, ip-address >= 10.7.1 and brace-expansion >= 5.0.12 exists. The secret-scanning and Scorecard workflows that used to ship here are now the separate `supply-chain` pack."
 }