@apollion-dsi/scripts 0.7.7 → 0.8.0

package/lib/utils/checkRequiredFiles.d.ts

@@ -1 +1,10 @@
+/**
+ * Verify every file in `files` exists on disk. Logs the first missing
+ * file to `console.log` (with chalk) and returns `false`; otherwise
+ * returns `true`. Used by the build/dev commands to fail fast before
+ * touching webpack.
+ *
+ * @param files  Absolute paths to required files (typically `paths.appHtml`,
+ *               `paths.appIndexJs`).
+ */
 export default function checkRequiredFiles(files: string[]): boolean;

package/lib/utils/checkRequiredFiles.js

@@ -7,6 +7,15 @@ exports.default = checkRequiredFiles;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const chalk_1 = __importDefault(require("chalk"));
+/**
+ * Verify every file in `files` exists on disk. Logs the first missing
+ * file to `console.log` (with chalk) and returns `false`; otherwise
+ * returns `true`. Used by the build/dev commands to fail fast before
+ * touching webpack.
+ *
+ * @param files  Absolute paths to required files (typically `paths.appHtml`,
+ *               `paths.appIndexJs`).
+ */
 function checkRequiredFiles(files) {
     let currentFilePath;
     try {

package/lib/utils/checkRequiredFiles.js.map

@@ -1 +1 @@
-{"version":3,"file":"checkRequiredFiles.js","sourceRoot":"","sources":["../../src/utils/checkRequiredFiles.ts"],"names":[],"mappings":";;;;;AAKA,qCAgBC;AArBD,4CAAoB;AACpB,gDAAwB;AAExB,kDAA0B;AAE1B,SAAwB,kBAAkB,CAAC,KAAe;IACxD,IAAI,eAAmC,CAAC;IACxC,IAAI,CAAC;QACH,KAAK,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE;YACzB,eAAe,GAAG,QAAQ,CAAC;YAC3B,YAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,YAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,eAAe,CAAC,CAAC,CAAC,cAAI,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,MAAM,QAAQ,GAAG,eAAe,CAAC,CAAC,CAAC,cAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACvE,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC,CAAC;QAC1D,OAAO,CAAC,GAAG,CAAC,KAAK,eAAK,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,eAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAC/D,OAAO,CAAC,GAAG,CAAC,KAAK,eAAK,CAAC,GAAG,CAAC,aAAa,CAAC,KAAK,eAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACrE,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}
+{"version":3,"file":"checkRequiredFiles.js","sourceRoot":"","sources":["../../src/utils/checkRequiredFiles.ts"],"names":[],"mappings":";;;;;AAcA,qCAgBC;AA9BD,4CAAoB;AACpB,gDAAwB;AAExB,kDAA0B;AAE1B;;;;;;;;GAQG;AACH,SAAwB,kBAAkB,CAAC,KAAe;IACxD,IAAI,eAAmC,CAAC;IACxC,IAAI,CAAC;QACH,KAAK,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE;YACzB,eAAe,GAAG,QAAQ,CAAC;YAC3B,YAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,YAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,eAAe,CAAC,CAAC,CAAC,cAAI,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,MAAM,QAAQ,GAAG,eAAe,CAAC,CAAC,CAAC,cAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACvE,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC,CAAC;QAC1D,OAAO,CAAC,GAAG,CAAC,KAAK,eAAK,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,eAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAC/D,OAAO,CAAC,GAAG,CAAC,KAAK,eAAK,CAAC,GAAG,CAAC,aAAa,CAAC,KAAK,eAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACrE,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/lib/utils/formatWebpackMessages.d.ts

@@ -1,5 +1,18 @@
+/**
+ * Normalized result of {@link formatWebpackMessages} — `errors` and
+ * `warnings` are always string arrays (empty if absent in the input).
+ */
 export type FormattedMessages = {
     errors: string[];
     warnings: string[];
 };
+/**
+ * Coerce webpack's `stats.toJson({ warnings, errors })` shape into a
+ * plain `{ errors, warnings }` of strings. Tolerates `null`, arrays of
+ * objects with `{ message, moduleName }`, raw primitives, or anything
+ * else (falls back to `JSON.stringify` / `String()`).
+ *
+ * @param json  Output of `stats.toJson({ warnings: true, errors: true })`
+ *              or any partially-shaped equivalent.
+ */
 export default function formatWebpackMessages(json: any): FormattedMessages;

package/lib/utils/formatWebpackMessages.js

@@ -24,6 +24,15 @@ function toString(item) {
     }
     return String(item);
 }
+/**
+ * Coerce webpack's `stats.toJson({ warnings, errors })` shape into a
+ * plain `{ errors, warnings }` of strings. Tolerates `null`, arrays of
+ * objects with `{ message, moduleName }`, raw primitives, or anything
+ * else (falls back to `JSON.stringify` / `String()`).
+ *
+ * @param json  Output of `stats.toJson({ warnings: true, errors: true })`
+ *              or any partially-shaped equivalent.
+ */
 function formatWebpackMessages(json) {
     const errors = Array.isArray(json?.errors) ? json.errors.map(toString) : [];
     const warnings = Array.isArray(json?.warnings) ? json.warnings.map(toString) : [];

package/lib/utils/formatWebpackMessages.js.map

@@ -1 +1 @@
-{"version":3,"file":"formatWebpackMessages.js","sourceRoot":"","sources":["../../src/utils/formatWebpackMessages.ts"],"names":[],"mappings":";;AAyBA,wCAIC;AAxBD,SAAS,QAAQ,CAAC,IAAa;IAC7B,IAAI,IAAI,IAAI,IAAI;QAAE,OAAO,EAAE,CAAC;IAC5B,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,IAAW,CAAC;QAC5B,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YACxC,IAAI,MAAM,GAAG,EAAE,CAAC;YAChB,IAAI,OAAO,CAAC,UAAU;gBAAE,MAAM,IAAI,MAAM,OAAO,CAAC,UAAU,MAAM,CAAC;YACjE,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;YAC1B,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACjC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC;AAED,SAAwB,qBAAqB,CAAC,IAAS;IACrD,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5E,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAClF,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"formatWebpackMessages.js","sourceRoot":"","sources":["../../src/utils/formatWebpackMessages.ts"],"names":[],"mappings":";;AAsCA,wCAIC;AAjCD,SAAS,QAAQ,CAAC,IAAa;IAC7B,IAAI,IAAI,IAAI,IAAI;QAAE,OAAO,EAAE,CAAC;IAC5B,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,IAAW,CAAC;QAC5B,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YACxC,IAAI,MAAM,GAAG,EAAE,CAAC;YAChB,IAAI,OAAO,CAAC,UAAU;gBAAE,MAAM,IAAI,MAAM,OAAO,CAAC,UAAU,MAAM,CAAC;YACjE,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;YAC1B,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACjC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC;AAED;;;;;;;;GAQG;AACH,SAAwB,qBAAqB,CAAC,IAAS;IACrD,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5E,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAClF,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAC9B,CAAC"}

package/lib/utils/getPublicUrlOrPath.d.ts

@@ -1 +1,20 @@
+/**
+ * Compute the absolute base URL (or path) every bundled asset is served from.
+ *
+ * Precedence: `envPublicUrl` → `homepage` → `'/'`.
+ *
+ * In **development**, absolute URLs collapse to their pathname so the
+ * dev-server doesn't try to fetch from a different origin; relative
+ * homepages (starting with `.`) collapse to `'/'` for the same reason.
+ *
+ * In **production**, the full URL (or pathname when only `homepage` is
+ * set) is preserved so CDN-rooted bundles resolve correctly.
+ *
+ * Adapted from `react-scripts` — semantics kept identical to ease migration.
+ *
+ * @param isEnvDevelopment  `true` when `NODE_ENV === 'development'`.
+ * @param homepage          `package.json#homepage` (project-level).
+ * @param envPublicUrl      `process.env.PUBLIC_URL` (per-invocation override).
+ * @returns A trailing-slash-normalized URL or absolute path.
+ */
 export default function getPublicUrlOrPath(isEnvDevelopment: boolean, homepage: string | undefined, envPublicUrl: string | undefined): string;

package/lib/utils/getPublicUrlOrPath.js

@@ -2,6 +2,25 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = getPublicUrlOrPath;
 const url_1 = require("url");
+/**
+ * Compute the absolute base URL (or path) every bundled asset is served from.
+ *
+ * Precedence: `envPublicUrl` → `homepage` → `'/'`.
+ *
+ * In **development**, absolute URLs collapse to their pathname so the
+ * dev-server doesn't try to fetch from a different origin; relative
+ * homepages (starting with `.`) collapse to `'/'` for the same reason.
+ *
+ * In **production**, the full URL (or pathname when only `homepage` is
+ * set) is preserved so CDN-rooted bundles resolve correctly.
+ *
+ * Adapted from `react-scripts` — semantics kept identical to ease migration.
+ *
+ * @param isEnvDevelopment  `true` when `NODE_ENV === 'development'`.
+ * @param homepage          `package.json#homepage` (project-level).
+ * @param envPublicUrl      `process.env.PUBLIC_URL` (per-invocation override).
+ * @returns A trailing-slash-normalized URL or absolute path.
+ */
 function getPublicUrlOrPath(isEnvDevelopment, homepage, envPublicUrl) {
     const stubDomain = 'https://create-react-app.dev';
     if (envPublicUrl) {

package/lib/utils/getPublicUrlOrPath.js.map

@@ -1 +1 @@
-{"version":3,"file":"getPublicUrlOrPath.js","sourceRoot":"","sources":["../../src/utils/getPublicUrlOrPath.ts"],"names":[],"mappings":";;AAEA,qCAoCC;AAtCD,6BAA0B;AAE1B,SAAwB,kBAAkB,CACxC,gBAAyB,EACzB,QAA4B,EAC5B,YAAgC;IAEhC,MAAM,UAAU,GAAG,8BAA8B,CAAC;IAElD,IAAI,YAAY,EAAE,CAAC;QACjB,IAAI,UAAU,GAAG,YAAY,CAAC;QAC9B,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,UAAU,IAAI,GAAG,CAAC;QACjD,IAAI,CAAC;YACH,MAAM,cAAc,GAAG,IAAI,SAAG,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;YACvD,OAAO,gBAAgB,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;QACtG,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,UAAU,CAAC;QACpB,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,UAAU,GAAG,QAAQ,CAAC;QAC1B,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,UAAU,IAAI,GAAG,CAAC;QACjD,IAAI,CAAC;YACH,MAAM,qBAAqB,GAAG,IAAI,SAAG,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC;YACvE,OAAO,gBAAgB;gBACrB,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC;oBAC1B,CAAC,CAAC,GAAG;oBACL,CAAC,CAAC,qBAAqB;gBACzB,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC;oBAC1B,CAAC,CAAC,UAAU;oBACZ,CAAC,CAAC,qBAAqB,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,UAAU,CAAC;QACpB,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"getPublicUrlOrPath.js","sourceRoot":"","sources":["../../src/utils/getPublicUrlOrPath.ts"],"names":[],"mappings":";;AAqBA,qCAoCC;AAzDD,6BAA0B;AAE1B;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAwB,kBAAkB,CACxC,gBAAyB,EACzB,QAA4B,EAC5B,YAAgC;IAEhC,MAAM,UAAU,GAAG,8BAA8B,CAAC;IAElD,IAAI,YAAY,EAAE,CAAC;QACjB,IAAI,UAAU,GAAG,YAAY,CAAC;QAC9B,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,UAAU,IAAI,GAAG,CAAC;QACjD,IAAI,CAAC;YACH,MAAM,cAAc,GAAG,IAAI,SAAG,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;YACvD,OAAO,gBAAgB,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;QACtG,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,UAAU,CAAC;QACpB,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,UAAU,GAAG,QAAQ,CAAC;QAC1B,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,UAAU,IAAI,GAAG,CAAC;QACjD,IAAI,CAAC;YACH,MAAM,qBAAqB,GAAG,IAAI,SAAG,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC;YACvE,OAAO,gBAAgB;gBACrB,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC;oBAC1B,CAAC,CAAC,GAAG;oBACL,CAAC,CAAC,qBAAqB;gBACzB,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC;oBAC1B,CAAC,CAAC,UAAU;oBACZ,CAAC,CAAC,qBAAqB,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,UAAU,CAAC;QACpB,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}

package/llms.txt

@@ -0,0 +1,52 @@
+# Apollion DS — @apollion-dsi/scripts
+
+Apollion's CRA-style CLI. Hides webpack 5 + Babel 7 + Jest 30 + TS 6
+behind four commands: `create`, `dev`, `build`, `test`.
+
+**Package:** `@apollion-dsi/scripts`. **Repo:**
+`github.com/apollion-ds/apollion`. **Bin:** `scripts` (from
+`lib/bin.js`).
+
+## Commands
+
+| `scripts <cmd>` | Effect |
+|---|---|
+| `create <name>` | Scaffold a new project from the template |
+| `dev` | webpack-dev-server + HMR (react-refresh) at :3000 |
+| `build` | Production bundle to `build/` |
+| `test` | Jest 30 in watch mode against changed files |
+
+Use via `package.json#scripts`:
+
+```json
+{ "scripts": { "dev": "scripts dev", "build": "scripts build", "test": "scripts test" } }
+```
+
+## Stack (hidden from consumer)
+
+- webpack 5 + Babel 7 (`preset-env`, `preset-react`, `preset-typescript`)
+- `babel-plugin-relay` + `babel-plugin-styled-components`
+- `react-refresh` for HMR
+- Jest 30 + ts-jest + `@testing-library/react`
+- Peer: **TypeScript 6.x**
+
+## Invariants
+
+* **Yarn only** (consumer template uses Yarn 4 Berry).
+* **No webpack config exposed.** If you need a config escape hatch,
+  open a ROADMAP entry — the point of this package is to not have one.
+* **TypeScript 6 strict** in the template — non-negotiable.
+
+## Files
+
+- `lib/bin.js` — CLI entry (resolved by `package.json#bin`).
+- `lib/index.js` — programmatic entry.
+- `src/` — TS sources.
+- `scripts/validate.sh` — workspace `validate` step.
+
+## Not in scope
+
+- Generic React boilerplate (template é opinionated p/ Apollion).
+- Storybook setup (use `@apollion-dsi/core` Storybook diretamente).
+- Monorepo orchestration (consumer monorepos usam yarn workspaces
+  diretamente).

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@apollion-dsi/scripts",
-  "version": "0.7.7",
+  "version": "0.8.0",
   "description": "Apollion Framework CLI",
   "main": "lib/index.js",
   "bin": "lib/bin.js",
   "scripts": {
     "prepare": "yarn build",
-    "audit-dependencies": "audit-ci --config audit-ci.json",
+    "audit-dependencies": "yarn npm audit --severity moderate --no-deprecations",
     "lint": "eslint src --quiet",
     "lint:full": "eslint src",
     "lint:fix": "eslint src --fix",
@@ -15,13 +15,16 @@
     "format": "yarn prettier --write",
     "validate": "./scripts/validate.sh",
     "test": "yarn validate",
+    "test:watch": "jest --watch",
+    "coverage": "jest --coverage",
+    "validate:tests": "jest --coverage",
     "build": "tsc -p ."
   },
   "keywords": [],
   "author": "Apollion DS Team",
   "license": "ISC",
   "dependencies": {
-    "@apollion-dsi/eslint-config": "0.6.0",
+    "@apollion-dsi/eslint-config": "0.7.0",
     "@babel/core": "7.29.0",
     "@babel/preset-env": "7.29.5",
     "@babel/preset-react": "7.28.5",
@@ -29,6 +32,7 @@
     "@pmmmwh/react-refresh-webpack-plugin": "0.6.2",
     "@testing-library/jest-dom": "6.9.1",
     "@testing-library/react": "16.3.2",
+    "babel-jest": "^30.4.1",
     "babel-loader": "10.1.1",
     "babel-plugin-named-asset-import": "0.3.8",
     "babel-plugin-relay": "20.1.1",
@@ -50,11 +54,12 @@
     "inquirer": "13.4.3",
     "jest": "30.4.2",
     "jest-cli": "30.4.2",
+    "jest-environment-node": "^30.4.1",
     "react-refresh": "0.18.0",
     "resolve": "1.22.12",
     "semver": "7.8.0",
     "terser-webpack-plugin": "5.6.0",
-    "ts-jest": "29.4.9",
+    "ts-jest": "^29.4.11",
     "tsconfig-paths-webpack-plugin": "4.2.0",
     "update-notifier": "7.3.1",
     "validate-npm-package-name": "8.0.0",
@@ -68,7 +73,6 @@
   "devDependencies": {
     "@testing-library/dom": "10.4.1",
     "@types/jest": "30.0.0",
-    "audit-ci": "7.1.0",
     "eslint": "9.29.0",
     "npm-run-all": "4.1.5",
     "prettier": "3.8.3",

package/scripts/validate.sh

@@ -4,13 +4,13 @@ BRANCH=$(git symbolic-ref --short HEAD)
 
 if [ "$BRANCH" = "main" ]; then
   echo "Validating on production"
-  npm-run-all --parallel check-types prettier lint && yarn build
+  npm-run-all --parallel check-types prettier lint && yarn validate:tests && yarn build
 
 elif [ "$BRANCH" = "staging" ]; then
   echo "Validating on staging"
-  npm-run-all --parallel check-types prettier lint && yarn build
+  npm-run-all --parallel check-types prettier lint && yarn validate:tests && yarn build
 
 else
   echo "Validating on development"
-  npm-run-all --parallel check-types prettier lint
+  npm-run-all --parallel check-types prettier lint && yarn validate:tests
 fi

package/src/__tests__/checkRequiredFiles.test.ts

@@ -0,0 +1,44 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import checkRequiredFiles from '../utils/checkRequiredFiles';
+
+describe('checkRequiredFiles', () => {
+  let tmpDir: string;
+  let logSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'apollion-scripts-'));
+    logSpy = jest.spyOn(console, 'log').mockImplementation(() => undefined);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    logSpy.mockRestore();
+  });
+
+  it('returns true when every file exists', () => {
+    const fileA = path.join(tmpDir, 'a.txt');
+    const fileB = path.join(tmpDir, 'b.txt');
+    fs.writeFileSync(fileA, '');
+    fs.writeFileSync(fileB, '');
+
+    expect(checkRequiredFiles([fileA, fileB])).toBe(true);
+    expect(logSpy).not.toHaveBeenCalled();
+  });
+
+  it('returns false and logs the missing file when one is absent', () => {
+    const present = path.join(tmpDir, 'present.txt');
+    const missing = path.join(tmpDir, 'missing.txt');
+    fs.writeFileSync(present, '');
+
+    expect(checkRequiredFiles([present, missing])).toBe(false);
+    const logs = logSpy.mock.calls.flat().join(' ');
+    expect(logs).toContain('missing.txt');
+  });
+
+  it('returns true for an empty list', () => {
+    expect(checkRequiredFiles([])).toBe(true);
+  });
+});

package/src/__tests__/env.test.ts

@@ -0,0 +1,51 @@
+import getClientEnvironment, { getEnviroment } from '../config/env';
+
+describe('getClientEnvironment', () => {
+  const savedEnv = { ...process.env };
+  afterEach(() => {
+    process.env = { ...savedEnv };
+  });
+
+  it('exposes REACT_APP_* vars in raw and stringified', () => {
+    process.env.REACT_APP_API_URL = 'https://api.example.com';
+    process.env.SECRET_KEY = 'leak-me-not';
+    process.env.NODE_ENV = 'production';
+
+    const result = getClientEnvironment('/public/', { useFastRefresh: false });
+    const raw = result.raw as Record<string, unknown>;
+
+    expect(raw.REACT_APP_API_URL).toBe('https://api.example.com');
+    expect(raw.PUBLIC_URL).toBe('/public/');
+    expect(raw.NODE_ENV).toBe('production');
+    expect(raw.FAST_REFRESH).toBe(false);
+
+    expect(raw).not.toHaveProperty('SECRET_KEY');
+    expect((result.stringified['process.env'] as Record<string, string>).PUBLIC_URL).toBe('"/public/"');
+  });
+
+  it('defaults NODE_ENV to "development" when unset', () => {
+    delete process.env.NODE_ENV;
+    const result = getClientEnvironment('/', { useFastRefresh: true });
+    expect(result.raw.NODE_ENV).toBe('development');
+    expect(result.raw.FAST_REFRESH).toBe(true);
+  });
+});
+
+describe('getEnviroment', () => {
+  const savedEnv = { ...process.env };
+  afterEach(() => {
+    process.env = { ...savedEnv };
+  });
+
+  it('throws when NODE_ENV is unset', () => {
+    delete process.env.NODE_ENV;
+    expect(() => getEnviroment({ dotenv: '/tmp/nonexistent.env' } as never)).toThrow(
+      /NODE_ENV environment variable is required/,
+    );
+  });
+
+  it('completes silently when no dotenv files exist', () => {
+    process.env.NODE_ENV = 'test';
+    expect(() => getEnviroment({ dotenv: '/tmp/definitely-missing.env' } as never)).not.toThrow();
+  });
+});

package/src/__tests__/formatWebpackMessages.test.ts

@@ -0,0 +1,42 @@
+import formatWebpackMessages from '../utils/formatWebpackMessages';
+
+describe('formatWebpackMessages', () => {
+  it('returns empty arrays when the input has no errors or warnings', () => {
+    expect(formatWebpackMessages(null)).toEqual({ errors: [], warnings: [] });
+    expect(formatWebpackMessages({})).toEqual({ errors: [], warnings: [] });
+    expect(formatWebpackMessages({ errors: 'not-array' })).toEqual({ errors: [], warnings: [] });
+  });
+
+  it('coerces string entries verbatim', () => {
+    expect(formatWebpackMessages({ errors: ['boom'], warnings: ['ouch'] })).toEqual({
+      errors: ['boom'],
+      warnings: ['ouch'],
+    });
+  });
+
+  it('prefixes object messages with their moduleName', () => {
+    expect(
+      formatWebpackMessages({
+        errors: [{ moduleName: 'src/a.ts', message: 'syntax error' }],
+        warnings: [{ message: 'unused export' }],
+      }),
+    ).toEqual({
+      errors: ['in src/a.ts\n\nsyntax error'],
+      warnings: ['unused export'],
+    });
+  });
+
+  it('stringifies unknown object shapes', () => {
+    expect(formatWebpackMessages({ errors: [{ code: 42 }] })).toEqual({
+      errors: ['{"code":42}'],
+      warnings: [],
+    });
+  });
+
+  it('coerces primitives to string', () => {
+    expect(formatWebpackMessages({ errors: [42, true] })).toEqual({
+      errors: ['42', 'true'],
+      warnings: [],
+    });
+  });
+});

package/src/__tests__/getPublicUrlOrPath.test.ts

@@ -0,0 +1,38 @@
+import getPublicUrlOrPath from '../utils/getPublicUrlOrPath';
+
+describe('getPublicUrlOrPath', () => {
+  describe('with envPublicUrl', () => {
+    it('returns the URL with trailing slash in production', () => {
+      expect(getPublicUrlOrPath(false, undefined, 'https://cdn.example.com/app')).toBe('https://cdn.example.com/app/');
+    });
+
+    it('returns absolute pathname in development for absolute URL', () => {
+      expect(getPublicUrlOrPath(true, undefined, 'https://cdn.example.com/app/')).toBe('/app/');
+    });
+
+    it('returns root in development when URL starts with "."', () => {
+      expect(getPublicUrlOrPath(true, undefined, './nested/')).toBe('/');
+    });
+  });
+
+  describe('with homepage only', () => {
+    it('returns the pathname in production for absolute homepage', () => {
+      expect(getPublicUrlOrPath(false, 'https://example.com/app/', undefined)).toBe('/app/');
+    });
+
+    it('returns root in development for absolute homepage', () => {
+      expect(getPublicUrlOrPath(true, 'https://example.com/app', undefined)).toBe('/app/');
+    });
+
+    it('returns relative homepage in production when starting with "."', () => {
+      expect(getPublicUrlOrPath(false, './app/', undefined)).toBe('./app/');
+    });
+  });
+
+  describe('with neither', () => {
+    it('returns root', () => {
+      expect(getPublicUrlOrPath(true, undefined, undefined)).toBe('/');
+      expect(getPublicUrlOrPath(false, undefined, undefined)).toBe('/');
+    });
+  });
+});

package/src/__tests__/paths.test.ts

@@ -0,0 +1,47 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+describe('createAppPaths', () => {
+  let tmpDir: string;
+  let savedCwd: string;
+
+  beforeEach(() => {
+    tmpDir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'apollion-scripts-paths-')));
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({ name: 'fixture', homepage: '/app/' }));
+    fs.writeFileSync(path.join(tmpDir, 'scriptsrc.js'), 'module.exports = { output: "dist" };');
+    fs.mkdirSync(path.join(tmpDir, 'src'));
+    fs.writeFileSync(path.join(tmpDir, 'src', 'index.tsx'), '// fixture entry');
+    fs.writeFileSync(path.join(tmpDir, 'src', 'setupTests.ts'), '// fixture setup');
+    savedCwd = process.cwd();
+  });
+
+  afterEach(() => {
+    process.chdir(savedCwd);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    jest.resetModules();
+  });
+
+  it('resolves every well-known path against the supplied base', () => {
+    process.chdir(tmpDir);
+    const { createAppPaths } = require('../config/paths');
+    const result = createAppPaths(tmpDir);
+
+    expect(result.appPath).toBe(tmpDir);
+    expect(result.appPackageJson).toBe(path.join(tmpDir, 'package.json'));
+    expect(result.appBuild).toBe(path.join(tmpDir, 'dist'));
+    expect(result.appHtml).toBe(path.join(tmpDir, 'public/index.html'));
+    expect(result.appIndexJs).toBe(path.join(tmpDir, 'src/index.tsx'));
+    expect(result.testsSetup).toBe(path.join(tmpDir, 'src/setupTests.ts'));
+    expect(result.moduleFileExtensions).toContain('tsx');
+    expect(result.publicUrlOrPath).toBe('/app/');
+  });
+
+  it('falls back to a `.js` extension when no source file matches', () => {
+    fs.rmSync(path.join(tmpDir, 'src', 'index.tsx'));
+    process.chdir(tmpDir);
+    const { createAppPaths } = require('../config/paths');
+    const result = createAppPaths(tmpDir);
+    expect(result.appIndexJs).toBe(path.join(tmpDir, 'src/index.js'));
+  });
+});

package/src/__tests__/shared.test.ts

@@ -0,0 +1,14 @@
+import { defaultDevConfig } from '../config/shared';
+
+describe('defaultDevConfig', () => {
+  it('exposes the expected dev defaults', () => {
+    expect(defaultDevConfig).toEqual({
+      port: 3000,
+      host: '0.0.0.0',
+      head: { title: 'Apollion' },
+      constants: {},
+      i18nConfig: {},
+      useFastRefresh: true,
+    });
+  });
+});

package/src/command/build.ts

@@ -95,6 +95,20 @@ function build(config: Configuration, previousFileSizes: unknown) {
   });
 }
 
+/**
+ * Run a one-shot webpack production build for the consumer app at `paths`.
+ *
+ * Side effects:
+ * - Sets `process.env.BABEL_ENV` / `NODE_ENV` to `'production'`.
+ * - Empties `paths.appBuild` and copies `paths.appPublic` into it.
+ * - On failure: prints the formatted error and exits with code 1
+ *   (or merely warns when `TSC_COMPILE_ON_ERROR=true`).
+ * - On `process.env.CI`-truthy runs, treats any webpack warning as a hard error.
+ *
+ * @param paths       Resolved app paths — typically `createAppPaths()`.
+ * @param userConfig  Optional override. Merged on top of {@link defaultDevConfig}.
+ *                    Pass `configureWebpack` here to mutate the final webpack config.
+ */
 export async function createProductionBuild(
   paths: AppPaths,
   userConfig: CustomConfigType = defaultDevConfig,

package/src/command/create/helper.ts

@@ -18,7 +18,6 @@ export const templateDependencies = [
   '@types/react-dom',
   '@types/react-router-dom',
   'styled-components',
-  '@types/styled-components',
   '@apollion-dsi/core',
   '@apollion-dsi/scripts',
   '@apollion-dsi/eslint-config',

package/src/command/dev.ts

@@ -22,6 +22,18 @@ import createDevServerConfig from '../config/webpackDevServer.config';
 import checkRequiredFiles from '../utils/checkRequiredFiles';
 import { choosePort, createCompiler, prepareProxy, prepareUrls } from '../utils/WebpackDevServerUtils';
 
+/**
+ * Boot a webpack-dev-server for the consumer app described by `paths`.
+ *
+ * Side effects:
+ * - Sets `process.env.BABEL_ENV` / `NODE_ENV` to `'development'`.
+ * - Picks an available port starting at `userConfig.port ?? 3000`.
+ * - Registers `SIGINT`/`SIGTERM` handlers that stop the server and exit.
+ *
+ * @param paths       Resolved app paths — typically `createAppPaths()`.
+ * @param userConfig  Optional override. Merged on top of {@link defaultDevConfig}.
+ *                    Pass `configureWebpack` here to mutate the final webpack config.
+ */
 export async function createDevServer(paths: AppPaths, userConfig: CustomConfigType = defaultDevConfig) {
   const useCustomConfig = fs.existsSync(paths.appCustomConfig);
 

package/src/config/env.ts

@@ -3,6 +3,16 @@ import path from 'path';
 
 import { CustomConfigType } from './shared';
 
+/**
+ * Load environment variables from `.env*` files in cascading order
+ * (`.env.<NODE_ENV>.local`, `.env.local`, `.env.<NODE_ENV>`, `.env`)
+ * and prepend the consumer's `NODE_PATH` entries with absolute paths.
+ *
+ * **Throws** when `process.env.NODE_ENV` is unset — required so the
+ * cascade can pick the right file. Skips `.env.local` for `NODE_ENV=test`.
+ *
+ * @param paths  `AppPaths` (only `paths.dotenv` is read).
+ */
 export function getEnviroment(paths) {
   const { NODE_ENV, ENV } = process.env;
 
@@ -43,6 +53,19 @@ export function getEnviroment(paths) {
     .join(path.delimiter);
 }
 
+/**
+ * Pick the `REACT_APP_*` subset of `process.env`, augment it with the
+ * fixed `NODE_ENV`/`PUBLIC_URL`/`WDS_SOCKET_*`/`FAST_REFRESH` keys, and
+ * return both the raw object (for runtime consumers) and a stringified
+ * form ready for webpack's `DefinePlugin`.
+ *
+ * **Security:** vars NOT prefixed with `REACT_APP_` (e.g. `SECRET_KEY`)
+ * are excluded — this is the boundary that prevents server-only secrets
+ * from leaking into the client bundle.
+ *
+ * @param publicUrl  `paths.publicUrlOrPath` — exposed as `PUBLIC_URL`.
+ * @param config     Resolved `CustomConfigType` (only `useFastRefresh` is read).
+ */
 export default function getClientEnvironment(publicUrl: string, config: CustomConfigType) {
   // Grab NODE_ENV and REACT_APP_* environment variables and prepare them to be
   // injected into the application via DefinePlugin in webpack configuration.