[task/TOF] phases 2–3: run-hugo, install:all, local smoke tests, CI matrix green

.github/workflows/smoke.yaml

@@ -41,7 +41,7 @@ jobs:
 
       - name: Setup workspace
         run: |
-          npm install
+          npm run install:all -- --omit=optional
           mkdir -p tmp && cd tmp && npm init -y
         shell: bash
 

.github/workflows/test.yaml

@@ -12,7 +12,7 @@ on:
   workflow_dispatch:
 permissions:
   contents: read
-  
+
 jobs:
   build:
     runs-on: ${{ matrix.os }}
@@ -29,7 +29,7 @@ jobs:
           cache: npm
           cache-dependency-path: package.json
 
-      - run: npm install --omit=optional
+      - run: npm run install:all -- --omit=optional
 
       - if: runner.os != 'Windows'
         run: npm run ci:test

package.json

@@ -10,7 +10,7 @@
   "scripts": {
     "__spv": "node scripts/set-package-version/index.mjs",
     "_check:afdocs": "npm run -s -C docsy.dev _check:afdocs",
-    "_check:format": "npx prettier --check theme/assets *.md theme/i18n scripts tasks",
+    "_check:format": "npx prettier --check theme/assets *.md theme/i18n scripts tasks tests",
     "_check:links": "npm run -C docsy.dev _check:links",
     "_check:markdown": "npx markdownlint-cli2",
     "_commit:public": "npm run -C docsy.dev _commit:public",
@@ -23,9 +23,9 @@
     "_prepare": "npm run _sync:theme-deps && npm run _cp:bs-rfs && npm run _prepare:scrollspy-patch && npm run _refresh-forward-sass-var && npm run _gen-chroma-styles && npm run get:hugo-modules",
     "_refresh-forward-sass-var": "bash -c scripts/refresh-sass-variables.pl",
     "_serve": "npm run -C docsy.dev _serve --",
-    "_sync:theme-deps": "node scripts/sync-theme-deps.mjs",
     "_spv:example": "echo TBC - npm run -s __spv docsy.dev/config/example/params.yaml --",
     "_spv": "npm run -s __spv docsy.dev/config/*/params.yaml --",
+    "_sync:theme-deps": "node scripts/sync-theme-deps.mjs",
     "build": "npm run -C docsy.dev build --",
     "check:afdocs:dev": "npm run -s _check:afdocs -- http://localhost:1313 | tee docsy.dev/content/en/docs/content/agent-support/afdocs-scorecard.txt",
     "check:format": "npm list prettier && npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)",
@@ -44,6 +44,7 @@
     "fix:markdown": "npm run check:markdown -- --fix",
     "fix": "npm run fix:format && npm run fix:markdown && npm run -C docsy.dev fix",
     "get:hugo-modules": "node scripts/getHugoModules/index.mjs",
+    "install:all": "npm run docsy.dev-install && npm install",
     "post-update": "echo; echo 'IMPORTANT! Run the following in case the ScrollSpy patch needs to be updated:\n  npm run _prepare'; echo",
     "postinstall": "npm run _mkdir:hugo-mod",
     "postupdate:dep": "npm run _sync:theme-deps && npm run -s post-update",
@@ -56,6 +57,8 @@
     "set:version:example": "cd ../docsy-example && node ../docsy/scripts/set-package-version/index.mjs",
     "set:version:git-info": "npm run -s _spv -- --version \"$(scripts/get-build-id.sh)\"",
     "set:version": "npm run -s _spv --",
+    "test:smoke-note": "echo 'FIXME: test:smoke pins --branch task/repo-reorg-2026-05 during the TOF rollout; remove that flag once the move merges to main (issue #2617).'",
+    "test:smoke": "node tests/smoke.test.mjs --branch task/repo-reorg-2026-05",
     "test:tooling": "node --test 'scripts/**/*.test.mjs'",
     "test:website": "npm run -C docsy.dev test",
     "test": "npm run fix-and-test",

scripts/_gen-chroma-style.sh

@@ -4,7 +4,8 @@
 
 set -eo pipefail
 
-HUGO="npx hugo"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HUGO="node $SCRIPT_DIR/run-hugo.mjs"
 CHROMA_STYLE=
 DEST_DIR=theme/assets/scss/td/chroma
 DEST_FILE=

scripts/getHugoModules/index.mjs

@@ -2,12 +2,15 @@
 // It gets dependency versions from `package.json`.
 
 import fs from 'fs';
+import path from 'path';
 import { execSync } from 'child_process';
 
+const SCRIPT_DIR = path.join(process.cwd(), 'scripts');
 const packageJson = readPackageJson();
 let exitStatus = 0;
 
 const exit = () => process.exit(exitStatus);
+const hugoCmd = () => `node ${SCRIPT_DIR}/run-hugo.mjs`;
 
 function getHugoModule(npmPkgNm, hugoModuleRefAtV) {
   try {
@@ -21,7 +24,7 @@ function getHugoModule(npmPkgNm, hugoModuleRefAtV) {
       throw new Error(msg);
     }
 
-    const command = `npx hugo mod get ${hugoModuleRefAtV}${pkgVers}`;
+    const command = `${hugoCmd()} mod get ${hugoModuleRefAtV}${pkgVers}`;
     console.log(`> (cd theme && ${command})`);
     const output = execSync(command, { cwd: 'theme' });
     console.log(output.toString());

scripts/make-site.sh

@@ -2,13 +2,15 @@
 # cSpell:ignore autoprefixer docsy postcss themesdir github oneline
 set -eo pipefail
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
 DEPS="autoprefixer postcss-cli"
 DOCSY_REPO_DEFAULT="google/docsy"
 DOCSY_REPO=$DOCSY_REPO_DEFAULT
 DOCSY_VERS=""
 DOCSY_SRC="NPM"
 FORCE_DELETE=false
-: ${HUGO:=npx hugo}
+: "${HUGO:=node $SCRIPT_DIR/run-hugo.mjs}"
 SITE_NAME="test-site"
 THEMESDIR="node_modules"
 VERBOSE=1

scripts/run-hugo.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// Resolve the installed `hugo-extended` and exec it with the forwarded args.
+// Reuses docsy.dev's install (the repo's single hugo-extended declaration,
+// version-pinned via package.json `config.hugo_version`) rather than `npx hugo`.
+// Cross-OS: runs the package's Node bin wrapper, not a POSIX symlink / Win shim.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const repoRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+);
+const searchBases = [path.join(repoRoot, 'docsy.dev'), repoRoot];
+
+function resolveHugoBin() {
+  for (const base of searchBases) {
+    // By node_modules path, not require.resolve('hugo-extended/package.json'):
+    // the package's `exports` blocks that (ERR_PACKAGE_PATH_NOT_EXPORTED).
+    const pkgDir = path.join(base, 'node_modules', 'hugo-extended');
+    const pkgJson = path.join(pkgDir, 'package.json');
+    if (!existsSync(pkgJson)) continue;
+    const { bin } = JSON.parse(readFileSync(pkgJson, 'utf8'));
+    const rel = typeof bin === 'string' ? bin : bin?.hugo;
+    if (rel) return path.join(pkgDir, rel);
+  }
+  return null;
+}
+
+const hugoBin = resolveHugoBin();
+if (!hugoBin) {
+  console.error(
+    '[run-hugo] hugo-extended not found — run `npm run install:all` first.',
+  );
+  process.exit(127);
+}
+
+const { status, error } = spawnSync(
+  process.execPath,
+  [hugoBin, ...process.argv.slice(2)],
+  { stdio: 'inherit' },
+);
+if (error) {
+  console.error(`[run-hugo] ${error.message}`);
+  process.exit(1);
+}
+process.exit(status ?? 1);

tasks/0.16/repo-reorg/README.md

@@ -22,25 +22,32 @@ Upstream tracking: issue [#2617][].
 [spike]: ./spike-notes.md
 [analysis]: ./monorepo-extra-analysis.md
 [#2617]: https://github.com/google/docsy/issues/2617
+[#2640]: https://github.com/google/docsy/pull/2640
 
 ## Status at a glance
 
-Updated 2026-05-24. Per-phase detail (with exit criteria) lives in the
-[execution plan][exec].
+Updated 2026-05-25. Per-phase detail (with exit criteria) lives in the
+[execution plan][exec]. **Phases 2 and 3 are now iterated as a pair** (like 0
+and 1): a local-only smoke pass does not close Phase 2 until the same matrix is
+green in CI.
 
-| Phase                                | Status                                                |
-| ------------------------------------ | ----------------------------------------------------- |
-| 0 — structural move                  | Landed; `_prepare` + `_diff:check` regression pending |
-| 1 — `docsy.dev` consumes TOF         | Local build green; Netlify preview pending            |
-| 2 — local smoke tests (CI emulation) | Pending; `make-site.sh` paths updated                 |
-| 3 — GitHub CI                        | Pending                                               |
-| 4 — `docsy-example`                  | Pending (post-pre-release)                            |
-| 5 — docs and release notes           | Pending                                               |
+| Phase                                | Status                                                          |
+| ------------------------------------ | --------------------------------------------------------------- |
+| 0 — structural move                  | Merged; `_prepare` + `_diff:check` regression pending           |
+| 1 — `docsy.dev` consumes TOF         | Local build green; Netlify deploy preview green ([#2640][])     |
+| 2 — local smoke tests (CI emulation) | Done — CI smoke matrix green ([#2640][])                        |
+| 3 — GitHub CI                        | Done — run-hugo + install:all; full CI matrix green ([#2640][]) |
+| 4 — `docsy-example`                  | Pending (post-pre-release)                                      |
+| 5 — docs and release notes           | Pending                                                         |
 
 Next concrete steps, in order:
 
-1. Re-run `npm run _prepare` and `npm run _diff:check` end-to-end against the
-   new layout to close out Phase 0.
-2. Push the branch and confirm a Netlify deploy preview of `docsy.dev` builds.
-3. Run `make-site.sh -s NPM`, then `-s HUGO_MODULE`, then a manual non-module
-   `themes/docsy/` clone-and-build. Record each in [spike-notes][spike].
+1. **Merge PR [#2640][]** — the full CI matrix is green (the Phase 3 decision
+   gate). The canonical move to `main` follows per the plan.
+2. Phase 0 carry-over: re-run `npm run _prepare` and `npm run _diff:check`
+   end-to-end against the new layout.
+3. Phase 4: land the `docsy-example` import-path bump (post pre-release).
+4. Phase 5: update the get-started "clone" docs for the new non-module setup
+   procedure recorded in [spike-notes][spike] Phase 2, plus changelog/blog.
+5. Later: formalize the smoke matrix as a local Vitest/TS harness — see the
+   execution plan's "Local test harness" section.