@hublo/sentinel 1.2.0-alpha.8 → 1.2.0

package/README.md

@@ -133,16 +133,31 @@ The per-tool knowledge (eslint → `eslint.config.js`, tsc → `tsconfig`, …)
 
 ## Requirements & installing
 
-**Registry: public npm**, under `@hublo`. We started on **GitHub Packages (private)** and moved off it: it authenticates every consumer, including a one-off `pnpm dlx`, which is incompatible with the zero-setup adoption above. Public npm needs no consumer auth, so a module adopts sentinel without any `.npmrc` or token. Releases go out through the repo's `publish` workflow, never from a laptop; a prerelease is published under its prerelease dist-tag (`alpha`) and a stable one under `latest`.
+**Registry: public npm**, under `@hublo`. We started on **GitHub Packages (private)** and moved off it: it authenticates every consumer, including a one-off run, which is incompatible with the zero-setup adoption above. Public npm needs no consumer auth, so a module adopts sentinel without any `.npmrc` or token. Releases go out through the repo's `publish` workflow, never from a laptop; a prerelease is published under its prerelease dist-tag (`alpha`) and a stable one under `latest`.
 
 **Node.** sentinel needs **Node >= 20.12** (its coloured output uses `util.styleText`, added in 20.12). It fails fast with a clear message on an older runtime rather than crashing. If a project runs on an older Node (e.g. a legacy app on Node 10), run sentinel with a modern Node via `fnm`/`nvm`; you do not need to change the project's own Node.
 
 **Try it without installing.** A one-off run needs no auth and touches nothing:
 
 ```bash
-pnpm dlx @hublo/sentinel@<exact-version> --inspect --typescript --module <name>
+npx --yes @hublo/sentinel@<exact-version> --inspect --typescript --module <name>
 ```
 
+**Why `npx` and not `pnpm dlx`, in a pnpm monorepo.** Because `pnpm dlx` no longer works for this,
+and no flag fixes it. pnpm's `strictDepBuilds` defaults to **true**, so adding a package whose build
+scripts have not been approved is a FATAL error rather than the warning it was through pnpm 10
+([settings/build](https://pnpm.io/settings/build)). sentinel pulls `esbuild` and `nx`, so the
+install aborts _before sentinel runs at all_: exit 1, nothing on stdout.
+
+The usual remedy, `allowBuilds` in `pnpm-workspace.yaml`, cannot reach it either: `dlx` runs in a
+throwaway project outside the workspace, so the workspace's approvals do not apply. `--allow-build`,
+`--config.dangerouslyAllowAllBuilds` and `--config.strictDepBuilds=false` were each measured and
+each still exits 1.
+
+`npx` fetches the same published package and runs no dependency build scripts, which is what a
+throwaway run wants. Once a module has adopted, nothing is fetched any more: the scripts call the
+`sentinel` binary from the module's own `devDependencies`.
+
 **Installing a pre-release (`minimumReleaseAge`).** The monorepo enforces a 3-day `minimumReleaseAge` supply-chain gate (a freshly published version cannot be installed until it has aged 3 days). A brand-new `alpha` therefore cannot be added yet, so while testing pre-releases you either exclude the package (`pnpm-workspace.yaml` → `minimumReleaseAgeExclude`) or install with `--config.minimumReleaseAge=0`. This is a deliberate protection, not a bug: **always pin the exact version** (`@hublo/sentinel@0.1.0-alpha.9`) rather than `@latest`, so a run is reproducible and the gate stays meaningful.
 
 ## Docs & cheat sheets

package/dist/bin/sentinel.d.ts

@@ -4,3 +4,4 @@ import '@vitejs/plugin-react';
 import 'nitro/vite';
 import 'vite-plugin-svgr';
 import 'vite';
+import 'vitest/config';

package/dist/bin/sentinel.js

@@ -8,6 +8,7 @@ import {
   VERBS,
   WORKSPACE_ROOT_MARKER,
   availableTargets,
+  buildConfigFile,
   declaredPresetFor,
   describeFramework,
   dispatch,
@@ -21,7 +22,7 @@ import {
   registerAdapters,
   resolve,
   resolveBin
-} from "../chunk-A25QVPXF.js";
+} from "../chunk-Z5I6SEKF.js";
 
 // bin/sentinel.ts
 import { program } from "commander";
@@ -113,6 +114,30 @@ function resolveContext(cwd2, opts2) {
   );
 }
 
+// src/roles/build/declined.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { join as join3 } from "path";
+var DEPRECATED_NX_BUILDER = "@nx/webpack:webpack";
+function buildsWithDeprecatedExecutor(cwd2) {
+  const projectJson = join3(cwd2, "project.json");
+  if (!existsSync2(projectJson)) return false;
+  try {
+    const project = JSON.parse(readFileSync2(projectJson, "utf8"));
+    return project.targets?.build?.executor === DEPRECATED_NX_BUILDER;
+  } catch {
+    return false;
+  }
+}
+function explainDecline(cwd2) {
+  if (buildConfigFile(cwd2) !== void 0) {
+    return ` This module HAS a Vite config, so detection is the likely problem: the build toolchain is declared at the workspace root, which makes a front app detect as "node". Pass --preset to say what it is.`;
+  }
+  if (buildsWithDeprecatedExecutor(cwd2)) {
+    return ` This module still builds through ${DEPRECATED_NX_BUILDER}, which Nx v24 removes. It has no Vite config yet, so there is nothing for --build to adopt: add one that imports @hublo/sentinel/build/nest, then run this again. See docs/build-adoption.md.`;
+  }
+  return ` This module has neither a Vite config nor an Nx build target, so it builds nothing and --build is out of scope for it. Nothing was written, and nothing is wrong.`;
+}
+
 // src/cli/run-init.ts
 function asMessage(error) {
   return error instanceof Error ? error.message : String(error);
@@ -151,9 +176,10 @@ async function runInit(ctx) {
     } catch (error) {
       if (error instanceof PresetUnsupportedError) {
         if (ctx.targetsExplicit) {
+          const hint = type === "build" ? explainDecline(module.root) : ` Pass --preset if it was detected wrongly (hoisted dependencies make detection fall back to "node").`;
           process.stderr.write(
             `
-sentinel (${type}): this module's preset is "${error.preset}", and --${type} has no adapter for it. Pass --preset if it was detected wrongly (hoisted dependencies make detection fall back to "node").
+sentinel (${type}): this module's preset is "${error.preset}", and --${type} has no adapter for it.${hint}
 `
           );
           worst = Math.max(worst, 1);