@stjoseph/prumo 0.4.3 → 0.5.1

package/.prumo-templates/core/testing.md

@@ -15,7 +15,8 @@ Do not mock `EntityManager` or any concrete class from a library.
 
 **In a client, replace the network through the injected transport**: pass a fake `fetch` to `createClient`.
 Do not add a request-mocking library. Test a component that shows an error by rendering it and asserting
-**where** the error appears.
+**where** the error appears. Build every test's `QueryClient` with `createTestQueryClient()` from
+`@test/support/query-client`, never with `new QueryClient()`: the defaults a test needs live there, once.
 
 Measure coverage and report it. Do not block a merge on a coverage threshold.
 
@@ -59,9 +60,18 @@ written in a mobile test is a mistake an assistant will make.
 is **asynchronous** and its matchers need no setup. `expo-secure-store` needs the native Keychain or Keystore,
 which Jest does not have, so a test builds the auth client with an in-memory token store, which is why a form
 asks only for the auth methods it calls. And `jest-expo` leaves the app manifest empty, so `expo-linking` cannot
-know the app's scheme: a test that reaches `Linking.createURL` mocks it with the scheme it expects. A test rendering a `useMutation` builds
-its `QueryClient` with `mutations: { gcTime: Infinity }`: once unmounted, the mutation otherwise starts TanStack
-Query's five-minute garbage-collection timer, and Jest force-exits the worker still waiting on it.
+know the app's scheme: a test that reaches `Linking.createURL` mocks it with the scheme it expects. And a query
+or mutation left without an observer once a test unmounts starts TanStack Query's five-minute garbage-collection
+timer, which Jest's worker waits on until it is force-exited. `createTestQueryClient()` sets `gcTime: Infinity`
+for both, so no timer starts, and `retry: false` for queries, so a failure shows at once: the two defaults TanStack
+Query's testing guide gives. Vitest does not wait on the timer, and `web` uses the same helper so that one rule
+holds in both.
+
+**`web` turns route code splitting off under Vitest**, in `vite.config.ts`. Split, a route's component is a module
+Vite transforms the first time a test renders it, inside the one second a `find*` query waits, and on a loaded CI
+runner the first page of a test file missed it. The wait is not the problem and is not raised: with the transform
+gone the same load passes, and past that load a longer wait fails the same tests anyway. **What it costs:** the
+tests never load a route's lazy chunk; the build and its preview do.
 
 A coverage threshold turns a proxy into a target. Whoever is below writes tests to raise the number rather
 than to check anything; whoever is above stops thinking. With no database mocks a test costs more to write,

package/README.md

@@ -33,7 +33,16 @@ workspace holding four applications, without either one carrying rules it has no
 ## Requirements
 
 Node 22.18 or later, pnpm 10.26 or later, and Docker for anything with an API. `prumo doctor` checks
-all of it. Prumo runs on macOS and Linux; Windows is not supported yet.
+all of it. Prumo runs on macOS, Linux and Windows.
+
+On Windows it runs natively: the project lives in a Windows folder, and the Windows Node and pnpm run it.
+Docker Desktop, with its WSL2 backend and set to Linux containers, is only where the database and the API's
+tests run.
+
+Inside a WSL distribution, with the distribution's own terminal, Node, pnpm and Docker, Prumo is on Linux, which is
+supported, though not tested on WSL specifically. Mixing the two is not supported: Windows tools, Prumo Desktop
+included, working on a project inside the WSL filesystem (`\\wsl$` or `\\wsl.localhost`).
+
 
 ## Running it
 
@@ -51,7 +60,9 @@ committed, so the first commit is yours and the diff shows everything Prumo wrot
 writes into the current directory instead, which must be empty, and names the project after it. If
 anything fails or is interrupted, Prumo removes what it wrote, so the same command can run again.
 A project cannot be named `api`, `web`, `mobile` or `site`: those are the names its apps take inside
-a workspace.
+a workspace. Nor can it take the name of a package that pnpm's compatibility database extends, such as `ws`:
+pnpm applies the extension to the project's own `package.json` and installs what it adds. Prumo names
+the packages and suggests another name.
 
 Every question also has a flag, which is how CI runs it without a terminal. Outside an interactive
 terminal every question that applies needs its flag, the layout of a single type included: a missing
@@ -79,7 +90,7 @@ npx @stjoseph/prumo new my-api --types api --alone --single-tenant --email
 | `prumo new [name \| .]` | Generates a project |
 | `prumo db` | Inside a project with an API: creates the development database in Docker and writes its URL into `.env` |
 | `prumo clean` | Removes what the project needed only once, today the database setup, once the database exists. Only the Prumo version that generated the project cleans it |
-| `prumo doctor` | Checks Node, pnpm, git and Docker on this machine |
+| `prumo doctor` | Checks Node, pnpm, git and Docker on this machine, and that Docker runs Linux containers |
 | `prumo version` · `--version` · `-v` | Prints the CLI version |
 | `prumo help [command]` · `--help` | Lists the commands, or describes one |
 
@@ -129,6 +140,7 @@ Once written, those documents belong to the team. Prumo does not come back and r
 | [`docs/structure.md`](https://github.com/stjosephworks/prumo/blob/main/docs/structure.md) | The `.prumo/` layout, and the rule deciding which areas a project receives |
 | [`docs/document-template.md`](https://github.com/stjosephworks/prumo/blob/main/docs/document-template.md) | The shape every convention document fills |
 | [`docs/maintaining-templates.md`](https://github.com/stjosephworks/prumo/blob/main/docs/maintaining-templates.md) | How a template is changed, and how the change is proved |
+| [`docs/upgrading.md`](https://github.com/stjosephworks/prumo/blob/main/docs/upgrading.md) | What each release changed in the files it generates, and how an existing project carries it over |
 
 ## Releasing
 
@@ -136,6 +148,14 @@ Once written, those documents belong to the team. Prumo does not come back and r
 registry does not have yet, the `publish` job sends it to npm through npm's trusted publishing, with provenance and
 without a token in the repository. Any other push to `main` publishes nothing.
 
+## Upgrading a project
+
+Prumo does not update a project it generated, and there is no `prumo upgrade`. For each release that changed
+the generated files, [`docs/upgrading.md`](https://github.com/stjosephworks/prumo/blob/main/docs/upgrading.md)
+lists what to copy or change and why, and gives one method: generate a reference project with the same answers
+at the old and the new version, and diff the files listed. A file your team has edited is merged by hand, never
+overwritten.
+
 ## Status
 
 Prumo is in beta: every template runs and every generated project is verified in CI, and what a generated project looks like can still change before 1.0.

package/dist/command.js

@@ -0,0 +1,17 @@
+import { spawnSync } from 'node:child_process';
+const windows = process.platform === 'win32';
+// Only what the CLI itself writes: no space, quote or shell operator, so one line means the same in any shell.
+const PLAIN = /^[\w@.:/={}-]+$/;
+// Runs a tool the CLI names, such as pnpm, git or docker. On Windows pnpm is a .cmd shim, which Node starts only
+// through a shell, and a shell given an argument list is deprecated (DEP0190), so there the command goes as one line.
+export function runCommand(command, args, options = {}) {
+    if (!windows) {
+        return spawnSync(command, args, options);
+    }
+    for (const part of [command, ...args]) {
+        if (!PLAIN.test(part)) {
+            throw new Error(`${part} cannot be passed through a shell unquoted`);
+        }
+    }
+    return spawnSync([command, ...args].join(' '), { ...options, shell: true });
+}

package/dist/compose.js

@@ -49,7 +49,10 @@ export async function copyTemplate(source, destination) {
 async function copyApp(templates, target, type) {
     const destination = join(target, 'apps', type);
     await copyTemplate(join(templates, type), destination);
-    await rm(join(destination, '.githooks'), { recursive: true, force: true });
+    // The workspace root carries both, for every app below it.
+    for (const rootOnly of ['.githooks', '.gitattributes']) {
+        await rm(join(destination, rootOnly), { recursive: true, force: true });
+    }
     return destination;
 }
 async function contractFiles(directory) {

package/dist/doctor.js

@@ -1,14 +1,15 @@
-import { spawnSync } from 'node:child_process';
+import { runCommand } from "./command.js";
 const NODE_FLOOR = [22, 18, 0];
 // Every generated workspace approves dependency builds with `allowBuilds`, which pnpm added in 10.26.0.
 const PNPM_FLOOR = [10, 26, 0];
-// On Windows pnpm is a .cmd shim, and Node starts one only through a shell.
-export const SHELL = process.platform === 'win32';
 export const systemProbe = {
     nodeVersion: process.versions.node,
     run: (command, args) => {
-        const result = spawnSync(command, args, { encoding: 'utf8', timeout: 10_000, shell: SHELL });
-        return { ok: result.error === undefined && result.status === 0, stdout: result.stdout ?? '' };
+        const result = runCommand(command, args, { encoding: 'utf8', timeout: 10_000 });
+        return {
+            ok: result.error === undefined && result.status === 0,
+            stdout: String(result.stdout ?? ''),
+        };
     },
 };
 function atLeast(version, floor) {
@@ -59,19 +60,25 @@ export async function doctor(probe = systemProbe) {
     });
     checks.push(...toolChecks(probe, ['pnpm', 'git']));
     const docker = probe.run('docker', ['--version']);
-    const dockerRunning = docker.ok && probe.run('docker', ['info']).ok;
+    const engine = docker.ok ? probe.run('docker', ['info', '--format', '{{.OSType}}']) : undefined;
+    const os = firstLine(engine?.stdout ?? '');
     checks.push({
         id: 'docker',
         label: 'Docker',
         required: false,
-        ...(dockerRunning
-            ? { status: 'ok', detail: firstLine(docker.stdout) }
-            : {
+        ...(engine?.ok !== true
+            ? {
                 status: 'warn',
                 detail: docker.ok
                     ? 'installed but not running; open Docker Desktop. The API runs its database and tests in it'
-                    : 'not found; install Docker Desktop. The API runs its database and tests in it',
-            }),
+                    : 'not found; install Docker Desktop, on Windows with the WSL2 backend. The API runs its database and tests in it',
+            }
+            : os !== 'linux'
+                ? {
+                    status: 'warn',
+                    detail: `running ${os || 'unknown'} containers; switch Docker Desktop to Linux containers. The API's Postgres image is a Linux one`,
+                }
+                : { status: 'ok', detail: firstLine(docker.stdout) }),
     });
     return { ready: checks.every((check) => !check.required || check.status === 'ok'), checks };
 }

package/dist/generate.js

@@ -1,11 +1,10 @@
-import { spawnSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { readdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { runCommand } from "./command.js";
 import { composeWorkspace, copyTemplate } from "./compose.js";
 import { writeContext } from "./context.js";
-import { SHELL } from "./doctor.js";
 import { applyFeatures, enabledFor } from "./features.js";
 import { setJsonc } from "./jsonc.js";
 import { schemeFor, targetProblem } from "./names.js";
@@ -78,10 +77,9 @@ function stopIfInterrupted() {
 function run(command, args, cwd, output) {
     stopIfInterrupted();
     // Under --json stdout belongs to the result document, so a child's output goes to stderr instead.
-    const result = spawnSync(command, args, {
+    const result = runCommand(command, args, {
         cwd,
         stdio: output === 'inherit' ? 'inherit' : ['ignore', 2, 2],
-        shell: SHELL,
     });
     // spawnSync holds the event loop, so the listener has not run yet; the child says it instead, either by dying of
     // the signal or, as pnpm does, by catching it and exiting with 130.

package/dist/names.js

@@ -1,5 +1,6 @@
 import { readdirSync, statSync } from 'node:fs';
 import { basename, resolve } from 'node:path';
+import { EXTENDED_BY_PNPM } from "./pnpm-extended.js";
 const PROJECT_NAME = /^[a-z][a-z0-9-]*$/;
 // npm refuses a longer package name.
 const MAX_LENGTH = 214;
@@ -15,7 +16,18 @@ export function validateProjectName(name) {
     if (RESERVED.includes(name)) {
         return 'That is the name an app takes inside a workspace; choose another.';
     }
-    return undefined;
+    return extendedByPnpm(name);
+}
+function extendedByPnpm(name) {
+    const added = Object.hasOwn(EXTENDED_BY_PNPM, name) ? EXTENDED_BY_PNPM[name] : undefined;
+    if (added === undefined) {
+        return undefined;
+    }
+    const shown = added.length > 3
+        ? `${added.slice(0, 3).join(', ')} and ${added.length - 3} more`
+        : added.join(', ');
+    return (`pnpm extends the npm package "${name}" with ${shown}, and would install them into a project of that name. ` +
+        `Choose another, such as "${name}-app".`);
 }
 // Why a directory cannot receive a project, or undefined when it can: it does not exist yet, or it is empty.
 export function targetProblem(target) {

package/dist/pnpm-extended.js

@@ -0,0 +1,159 @@
+// pnpm applies a compatibility database, @yarnpkg/extensions, to every manifest it reads: the registry's packages and
+// the project's own package.json alike. An entry matches by name and version range, and the template version 0.0.1
+// falls inside ranges like `ws@<7.2.1`. A project carrying one of these names therefore gains the dependencies the
+// entry adds, installed into its root, and a package among them with a build script stops `pnpm install` with
+// ERR_PNPM_IGNORED_BUILDS. Each name maps to the packages it would add.
+//
+// Derived from @yarnpkg/extensions, pinned in devDependencies, by test/names.spec.ts, which fails when this list and
+// the database part ways. Only names a project can take are kept, and only entries that add a package: one that sets
+// nothing but peerDependenciesMeta changes no install.
+export const EXTENDED_BY_PNPM = {
+    'apollo-upload-client': ['graphql'],
+    'auto-relay': ['reflect-metadata'],
+    'babel-plugin-graphql-tag': ['graphql'],
+    'babel-plugin-remove-graphql-queries': ['@babel/runtime', '@babel/types', 'gatsby-core-utils'],
+    'babel-plugin-transform-typescript-metadata': ['@babel/core', '@babel/traverse'],
+    'babel-preset-gatsby-package': ['@babel/runtime'],
+    'bin-links': ['mkdirp-infer-owner'],
+    'cacheable-lookup': ['@types/keyv'],
+    'clipanion-v3-codemod': ['jscodeshift'],
+    'connect-mongo': ['express-session'],
+    consolidate: [
+        'arc-templates',
+        'atpl',
+        'babel-core',
+        'bracket-template',
+        'coffee-script',
+        'dot',
+        'dust',
+        'dustjs-helpers',
+        'dustjs-linkedin',
+        'eco',
+        'ect',
+        'ejs',
+        'haml-coffee',
+        'hamlet',
+        'hamljs',
+        'handlebars',
+        'hogan.js',
+        'htmling',
+        'jade',
+        'jazz',
+        'jqtpl',
+        'just',
+        'liquid-node',
+        'liquor',
+        'lodash',
+        'marko',
+        'mote',
+        'mustache',
+        'nunjucks',
+        'plates',
+        'pug',
+        'qejs',
+        'ractive',
+        'razor-tmpl',
+        'react',
+        'react-dom',
+        'slm',
+        'squirrelly',
+        'swig',
+        'swig-templates',
+        'teacup',
+        'templayed',
+        'then-jade',
+        'then-pug',
+        'tinyliquid',
+        'toffee',
+        'twig',
+        'twing',
+        'underscore',
+        'vash',
+        'velocityjs',
+        'walrus',
+        'whiskers',
+    ],
+    'cordova-ios': ['underscore'],
+    'cordova-lib': ['underscore'],
+    'create-gatsby': ['@babel/runtime'],
+    'elm-webpack-loader': ['temp'],
+    'eslint-import-resolver-vite': ['debug', 'resolve'],
+    fdir: ['picomatch'],
+    'fork-ts-checker-webpack-plugin': ['eslint', 'typescript', 'vue-template-compiler', 'webpack'],
+    'gatsby-admin': ['@babel/runtime'],
+    'gatsby-cli': ['@babel/runtime'],
+    'gatsby-core-utils': ['@babel/runtime', 'got'],
+    'gatsby-design-tokens': ['@babel/runtime'],
+    'gatsby-legacy-polyfills': ['@babel/runtime'],
+    'gatsby-plugin-benchmark-reporting': ['@babel/runtime'],
+    'gatsby-plugin-favicon': ['webpack'],
+    'gatsby-plugin-gatsby-cloud': ['gatsby-core-utils', 'webpack'],
+    'gatsby-plugin-graphql-config': ['@babel/runtime'],
+    'gatsby-plugin-i18n': ['ramda'],
+    'gatsby-plugin-image': ['@babel/runtime'],
+    'gatsby-plugin-mdx': ['@babel/runtime', 'mkdirp'],
+    'gatsby-plugin-netlify-cms': ['@babel/runtime'],
+    'gatsby-plugin-no-sourcemaps': ['@babel/runtime'],
+    'gatsby-plugin-page-creator': ['@babel/runtime', 'fs-extra'],
+    'gatsby-plugin-preact': ['@babel/runtime'],
+    'gatsby-plugin-preload-fonts': ['@babel/runtime'],
+    'gatsby-plugin-schema-snapshot': ['@babel/runtime'],
+    'gatsby-plugin-sharp': ['debug'],
+    'gatsby-plugin-styletron': ['@babel/runtime'],
+    'gatsby-plugin-subfont': ['@babel/runtime'],
+    'gatsby-plugin-utils': ['@babel/runtime', 'fastq', 'graphql'],
+    'gatsby-react-router-scroll': ['prop-types'],
+    'gatsby-recipes': ['@babel/runtime'],
+    'gatsby-remark-prismjs': ['lodash'],
+    'gatsby-source-apiserver': ['babel-polyfill'],
+    'gatsby-source-shopify': ['@babel/runtime'],
+    'gatsby-source-wikipedia': ['@babel/runtime'],
+    'gatsby-transformer-screenshot': ['@babel/runtime'],
+    'gatsby-worker': ['@babel/runtime'],
+    'git-node-fs': ['js-git'],
+    got: ['@types/keyv', '@types/responselike'],
+    'http-link-dataloader': ['graphql'],
+    'ink-select-input': ['react'],
+    'jest-vue-preprocessor': ['@babel/core', '@babel/template', 'pug'],
+    'jss-plugin-rule-value-function': ['tiny-warning'],
+    mqtt: ['duplexify'],
+    'query-ast': ['lodash'],
+    'rc-animate': ['react', 'react-dom'],
+    'react-bootstrap-table2-paginator': ['classnames'],
+    'react-color': ['react'],
+    'react-dev-utils': ['typescript', 'webpack'],
+    'react-draggable': ['react', 'react-dom'],
+    'react-github-btn': ['react'],
+    'react-instantsearch-core': ['algoliasearch'],
+    'react-instantsearch-dom': ['react-fast-compare'],
+    'react-live': ['react', 'react-dom'],
+    'react-portal': ['react-dom'],
+    'react-rnd': ['react', 'react-dom'],
+    'react-scripts': ['eslint', 'react'],
+    reactcss: ['react'],
+    rebass: ['react'],
+    'redux-persist': ['react'],
+    'redux-thunk': ['redux'],
+    'rollup-plugin-polyfill-node': ['rollup'],
+    'scss-parser': ['lodash'],
+    skypack: ['tar'],
+    snowpack: ['magic-string'],
+    terser: ['acorn'],
+    testcafe: ['@babel/plugin-transform-for-of', '@babel/runtime'],
+    'testcafe-legacy-api': ['read-file-relative', 'testcafe-hammerhead'],
+    'typescript-language-server': ['vscode-jsonrpc', 'vscode-languageserver-protocol'],
+    unified: ['@types/unist'],
+    'unplugin-vue2-script-setup': ['@vue/composition-api', '@vue/runtime-dom'],
+    'vite-plugin-vuetify': ['vue'],
+    'volar-service-typescript': ['typescript'],
+    'volar-service-typescript-twoslash-queries': ['typescript'],
+    'vue-cli-plugin-vuetify': ['null-loader', 'semver'],
+    'vue-i18n': ['vue'],
+    'vue-loader': ['@vue/compiler-sfc', 'webpack'],
+    'vue-router': ['vue'],
+    'vue-template-babel-compiler': ['vue-template-compiler'],
+    'webpack-plugin-vuetify': ['vue'],
+    'winston-transport': ['logform'],
+    ws: ['bufferutil', 'utf-8-validate'],
+    xo: ['webpack'],
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stjoseph/prumo",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "description": "Scaffolds a TypeScript project and ships it the conventions it follows, in a .prumo/ folder any AI assistant reads.",
   "keywords": [
     "scaffolding",
@@ -36,7 +36,7 @@
   "scripts": {
     "lint": "biome check",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run --dir test",
+    "test": "vitest run --dir test --test-timeout 30000",
     "prumo": "node src/cli.ts",
     "build": "tsc -p tsconfig.build.json && node scripts/copy-assets.mjs",
     "prepack": "pnpm build"
@@ -48,6 +48,9 @@
   "devDependencies": {
     "@biomejs/biome": "2.5.13",
     "@types/node": "24.13.4",
+    "@types/semver": "7.8.0",
+    "@yarnpkg/extensions": "2.0.7",
+    "semver": "7.8.5",
     "typescript": "6.0.3",
     "vitest": "4.1.11"
   },

package/templates/api/.gitattributes

@@ -0,0 +1,2 @@
+# LF in every checkout, Windows included: Biome formats to LF and would otherwise flag every file.
+* text=auto eol=lf

package/templates/api/README.md

@@ -3,6 +3,8 @@
 ## Requirements
 
 Node 22.18 or later, pnpm 10.26 or later, and Docker Desktop running: the database and the tests both run in it.
+On Windows, Docker Desktop needs its WSL2 backend and Linux containers. Keep the project in a Windows folder, or
+work entirely inside a WSL distribution; Windows tools on a project inside the WSL filesystem are not supported.
 
 ## Running it
 

package/templates/api/scripts/database.mjs

@@ -267,7 +267,8 @@ async function main() {
 
   if (!values['skip-migrate']) {
     say('Migrating…')
-    if (spawnSync('pnpm', ['db:migrate'], { cwd: api, stdio: childStdio }).status !== 0) {
+    // One line through the shell: on Windows pnpm is a .cmd shim, which Node starts only that way.
+    if (spawnSync('pnpm db:migrate', { cwd: api, stdio: childStdio, shell: true }).status !== 0) {
       throw new Failure(
         'migrate_failed',
         '`pnpm db:migrate` failed. The database exists and .env points at it.',