@stjoseph/prumo 0.4.0 → 0.4.2

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

@@ -55,11 +55,13 @@ been published since January 2024. Every other rule here (placement, no database
 behaviour) holds unchanged. **What it costs:** two runners in one workspace with near-identical APIs, so `vi.fn`
 written in a mobile test is a mistake an assistant will make.
 
-**Three things a mobile test meets, verified with Expo SDK 57:** `render` from `@testing-library/react-native` 14
+**Four things a mobile test meets, verified with Expo SDK 57:** `render` from `@testing-library/react-native` 14
 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.
+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.
 
 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/.prumo-templates/database/migrations.md

@@ -11,6 +11,8 @@ boot, and never by hand.
 Make every migration compatible with the **previous** release. Removing a column is two deployments:
 one that stops using it, one that removes it.
 
+Keep the `package.json` in the migrations directory. It holds only `"type": "module"`.
+
 Delete the generated `down`. Undoing a schema change is a new migration going forward.
 
 Keep DDL and data apart. A migration performs DDL only. Filling existing rows is a separate task, run
@@ -31,6 +33,12 @@ migration fails. It would also mean **the process serving requests holds DDL per
 injection or compromise could drop a table. A separate step lets the deploy use a privileged user for
 thirty seconds while the application runs as one that only reads and writes rows.
 
+The migrations are TypeScript that Node loads directly, by type stripping; the build never compiles
+them. They use `import`, and without a declared module type Node guesses: it fails to parse them as
+CommonJS, reparses them as ES modules, and warns `MODULE_TYPELESS_PACKAGE_JSON` in every process that
+runs them. The nearest `package.json` decides a file's type, so the one in the migrations directory
+settles it for those files alone and leaves the CommonJS build untouched.
+
 During a rolling deploy the previous version is still running against the new schema, so a migration
 that removes something the old code reads breaks production before the new version finishes arriving.
 

package/.prumo-templates/monorepo/tasks.md

@@ -31,7 +31,7 @@ choice rather than an accident. The root scripts call `dev` and nothing else, wh
 that name: the root never needs to know how each framework spells its development command.
 
 **Mobile gives up its terminal under `pnpm dev`.** Metro starts and serves, so an open simulator connects, but
-the QR code, the `exp://` URL and the keyboard shortcuts appear only when Expo owns the terminal. When you need
+the QR code, the URL a device opens and the keyboard shortcuts appear only when Expo owns the terminal. When you need
 them, run `pnpm mobile` in a terminal of its own.
 
 Ports are fixed per app because `pnpm dev` starts them together, and a collision there fails only when two apps

package/README.md

@@ -25,9 +25,9 @@ conventions that code follows. Any AI assistant working in that repository reads
 knows the rules without anyone explaining them, which is the whole point: **the conventions live in
 the project, not in someone's head.**
 
-Applications differ, so the choices are not one fixed bundle. Three answers shape what arrives:
-which artefacts the project has, whether they sit alone or in one workspace, and whether the
-application serves several tenants. The same body of decisions covers an API on its own and a
+Applications differ, so the choices are not one fixed bundle. The answers shape what arrives:
+which artefacts the project has, whether they sit alone or in one workspace, whether the application
+serves several tenants, and whether it ships MCP, email verification and sign-in with a provider. The same body of decisions covers an API on its own and a
 workspace holding four applications, without either one carrying rules it has no use for.
 
 ## Requirements

package/dist/cli.js

@@ -9,6 +9,7 @@ import { runDatabase } from "./database.js";
 import { doctor, doctorText, systemProbe, toolChecks } from "./doctor.js";
 import { generate } from "./generate.js";
 import { projectProblem } from "./names.js";
+import { nextSteps } from "./next-steps.js";
 import { CliError, errorEnvelope, writeEnvelope } from "./output.js";
 import { resolveAnswers } from "./questions.js";
 import { cliVersion } from "./version.js";
@@ -90,6 +91,14 @@ async function runNew(args, json) {
     });
     if (!json) {
         prompt.outro(`Created ${answers.name}.`);
+        const steps = nextSteps({
+            target,
+            cwd,
+            types: chosen.types,
+            architecture: chosen.architecture,
+            installed: install,
+        });
+        process.stdout.write(`Next:\n${steps.map((step) => `  ${step}\n`).join('')}`);
     }
     return { data: { ...chosen, target, installed: install, warnings }, text: '' };
 }

package/dist/compose.js

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { cp, mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
-import { applyFeatures, NONE } from "./features.js";
+import { applyFeatures, cutFeatures, NONE } from "./features.js";
 import { prependProperty, readJsonc, removeWhatBaseDeclares, setJsonc } from "./jsonc.js";
 const CLIENTS = ['web', 'mobile'];
 // One exception to one-version-per-dependency: stable NativeWind needs Tailwind 3.
@@ -185,6 +185,9 @@ async function assertCatalogCovers(target, catalog) {
 export async function composeWorkspace({ templates, target, types, features = NONE, }) {
     await mkdir(target, { recursive: true });
     await copyTemplate(join(templates, 'workspace'), target);
+    // The root README tells a first run what the features change, so it is cut like any app's.
+    const readme = join(target, 'README.md');
+    await writeFile(readme, cutFeatures(await readFile(readme, 'utf8'), features, readme));
     const apps = [];
     for (const type of types) {
         const app = await copyApp(templates, target, type);

package/dist/features.js

@@ -4,7 +4,7 @@ import { join } from 'node:path';
 import { setJsonc } from "./jsonc.js";
 // What a project may leave out. The templates ship with every one of them; a project that answered no receives the
 // template without it: these files deleted, these dependencies removed, and every line or block marked
-// `// prumo:<feature>` cut. A feature a type does not list has nothing to cut there.
+// `// prumo:<feature>` cut, READMEs included. A feature a type does not list has nothing to cut there.
 export const FEATURE_NAMES = ['mcp', 'email', 'social', 'google', 'apple'];
 export const SOCIAL_PROVIDERS = ['google', 'apple'];
 export const NONE = {
@@ -145,10 +145,10 @@ export const FEATURES = {
     apple: { files: {}, dependencies: {} },
 };
 export function cutFeature(text, feature, keep, file = 'a file') {
-    // Inside JSX a comment is written {/* … */}, and in an env file with #, so a block may open and close any of
-    // these ways.
-    const start = new RegExp(`^\\s*(// prumo:${feature}|\\{/\\* prumo:${feature} \\*/\\}|# prumo:${feature})$`);
-    const end = new RegExp(`^\\s*(// prumo:end-${feature}|\\{/\\* prumo:end-${feature} \\*/\\}|# prumo:end-${feature})$`);
+    // Inside JSX a comment is written {/* … */}, in an env file with #, and in Markdown as <!-- … -->, so a block may
+    // open and close any of these ways.
+    const start = new RegExp(`^\\s*(// prumo:${feature}|\\{/\\* prumo:${feature} \\*/\\}|# prumo:${feature}|<!-- prumo:${feature} -->)$`);
+    const end = new RegExp(`^\\s*(// prumo:end-${feature}|\\{/\\* prumo:end-${feature} \\*/\\}|# prumo:end-${feature}|<!-- prumo:end-${feature} -->)$`);
     // A marked import keeps its marker as a trailing comment, which the import sorter carries along.
     const marked = new RegExp(`\\s*(//|#) prumo:${feature}$`);
     const kept = [];
@@ -180,6 +180,9 @@ export function cutFeature(text, feature, keep, file = 'a file') {
     }
     return kept.join('\n');
 }
+export function cutFeatures(text, enabled, file = 'a file') {
+    return FEATURE_NAMES.reduce((current, feature) => cutFeature(current, feature, enabled[feature], file), text);
+}
 async function sourceFiles(directory) {
     if (!existsSync(directory)) {
         return [];
@@ -193,8 +196,9 @@ export async function applyFeatures(app, type, enabled) {
     const sources = [
         ...(await sourceFiles(join(app, 'src'))),
         ...(await sourceFiles(join(app, 'test'))),
-        // The settings a feature needs are cut with it.
+        // The settings a feature needs are cut with it, and so is what the README says about it.
         join(app, '.env.example'),
+        join(app, 'README.md'),
     ];
     const manifest = join(app, 'package.json');
     let pkg = await readFile(manifest, 'utf8');
@@ -219,7 +223,7 @@ export async function applyFeatures(app, type, enabled) {
             continue;
         }
         const text = await readFile(source, 'utf8');
-        const cut = FEATURE_NAMES.reduce((current, feature) => cutFeature(current, feature, enabled[feature], source), text);
+        const cut = cutFeatures(text, enabled, source);
         if (dropped.some((dependency) => cut.includes(`'${dependency}`))) {
             throw new Error(`${source} still imports a package that was removed, outside its marker`);
         }

package/dist/next-steps.js

@@ -0,0 +1,24 @@
+import { relative } from 'node:path';
+// What to type after `prumo new`, built from the scripts the templates ship rather than written per case. Every app
+// and every workspace root answers to `pnpm dev`; an API's `dev` first offers to create the database, and a mobile
+// app opens only in a development build, which its `ios` and `android` scripts make.
+export function nextSteps({ target, cwd, types, architecture, installed, }) {
+    const steps = [];
+    const directory = relative(cwd, target);
+    if (directory !== '') {
+        steps.push([`cd ${/\s/.test(directory) ? `"${directory}"` : directory}`]);
+    }
+    if (!installed) {
+        steps.push(['pnpm install']);
+    }
+    if (types.includes('mobile')) {
+        const run = architecture === 'alone' ? 'pnpm' : 'pnpm --filter mobile';
+        steps.push([`${run} ios`, 'or android: the development build the mobile app opens in']);
+    }
+    steps.push([
+        'pnpm dev',
+        types.includes('api') ? 'offers to create the database first' : undefined,
+    ]);
+    const width = Math.max(...steps.map(([command]) => command.length));
+    return steps.map(([command, why]) => why === undefined ? command : `${command.padEnd(width)}  # ${why}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stjoseph/prumo",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Scaffolds a TypeScript project and ships it the conventions it follows, in a .prumo/ folder any AI assistant reads.",
   "keywords": [
     "scaffolding",

package/templates/api/README.md

@@ -32,6 +32,25 @@ it spawned, stops them, and frees the port. Anything it did not start is named a
 
 Authentication is the API's own: `/api/auth/sign-up`, `sign-in`, `refresh`, `sign-out` and `session`. The web
 receives httpOnly cookies; a native client sends `X-Auth-Transport: bearer` and receives the tokens in the body.
+<!-- prumo:email -->
+
+An account must confirm its email before it can sign in. `/api/auth/email/verification` and `/api/auth/email/verify`
+send and check the 6-digit code, and `/api/auth/password/forgot` and `/api/auth/password/reset` do the same for a new
+password. No mail is sent yet: the `Mailer` port's only adapter, `LogMailer`, writes each mail to this API's log, in
+a line starting `[mail] to`, so read the code there. Sending real mail is another adapter behind the same port; see
+`.prumo/email/mailer.md`.
+<!-- prumo:end-email -->
+<!-- prumo:social -->
+
+Sign-in with a provider starts at `/api/auth/social/<provider>` and comes back to its `callback`. Until a provider's
+settings are filled in `.env`, it answers `provider_not_configured`; `.env.example` lists them and says where each
+one comes from.
+<!-- prumo:end-social -->
+<!-- prumo:mcp -->
+
+The MCP server answers at `/api/mcp`. This API is also the OAuth authorization server that issues its tokens: an MCP
+client finds it through `/.well-known/oauth-protected-resource`, and the user signs in and consents on the web app.
+<!-- prumo:end-mcp -->
 
 ## Everyday commands
 

package/templates/api/migrations/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/templates/api/test/support/global-setup.ts

@@ -1,7 +1,7 @@
 import { PostgreSqlContainer, type StartedPostgreSqlContainer } from '@testcontainers/postgresql'
 import type { TestProject } from 'vitest/node'
 
-let container: StartedPostgreSqlContainer
+let container: StartedPostgreSqlContainer | undefined
 
 export async function setup(project: TestProject): Promise<void> {
   container = await new PostgreSqlContainer('postgres:18-alpine').start()
@@ -9,8 +9,10 @@ export async function setup(project: TestProject): Promise<void> {
   project.provide('postgresUrl', container.getConnectionUri())
 }
 
+// Vitest still tears down when setup threw, as when the image could not be pulled; there is no container then, and
+// failing here would print a second error over the one that matters.
 export async function teardown(): Promise<void> {
-  await container.stop()
+  await container?.stop()
 }
 
 declare module 'vitest' {

package/templates/mobile/README.md

@@ -2,16 +2,23 @@
 
 ## Requirements
 
-Node 22.18 or later, pnpm 10.26 or later, and the API running. A simulator or a device with Expo Go
-to open the app.
+Node 22.18 or later, pnpm 10.26 or later, and the API running. To open the app, a simulator or a device with a
+development build of it, made on this machine with Xcode for iOS or Android Studio for Android. Expo Go cannot open
+it, because MMKV's native code is not part of Expo Go.
 
 ## Running it
 
 ```sh
 pnpm install
-pnpm dev
+pnpm ios       # or pnpm android: builds the development build, installs it, and serves it
+pnpm dev       # afterwards, until a native dependency changes
 ```
 
+`pnpm ios` and `pnpm android` run `expo run:ios` and `expo run:android`, which generate the native project the first
+time and compile it, so the first run is the slow one. `pnpm dev` then only serves the JavaScript, and the installed
+build opens it, because `expo-dev-client` makes `expo start` target the development build rather than Expo Go.
+Build again after adding or upgrading a package with native code.
+
 `.env` comes with the generated project, copied from `.env.example`; `EXPO_PUBLIC_API_URL` points at the API. It is
 not committed, so on a fresh clone run `cp .env.example .env`.
 
@@ -26,11 +33,17 @@ Ctrl+C stops everything `pnpm dev` started, not only what the terminal signals:
 it spawned, stops them, and frees the port. Anything it did not start is named and left alone.
 
 On an Android emulator `localhost` is the emulator itself; point `EXPO_PUBLIC_API_URL` at your machine's address.
+<!-- prumo:email -->
+
+Signing up first asks for the 6-digit code that confirms the email. No mail is sent yet: the API writes it to its
+log, in a line starting `[mail] to`, and a forgotten password works the same way.
+<!-- prumo:end-email -->
 
 ## Everyday commands
 
 | Command | What it does |
 |---|---|
+| `pnpm ios` · `pnpm android` | Builds and installs the development build, then serves it. Xcode or Android Studio |
 | `pnpm test` | Jest with `jest-expo`, rendering components against a fake transport; no API needed |
 | `pnpm lint` | Biome |
 | `pnpm typecheck` | `tsc --noEmit`, also run before every push |

package/templates/mobile/package.json

@@ -6,8 +6,8 @@
   "scripts": {
     "start": "expo start",
     "dev": "node scripts/ports.mjs -- expo start",
-    "ios": "expo start --ios",
-    "android": "expo start --android",
+    "ios": "node scripts/ports.mjs -- expo run:ios",
+    "android": "node scripts/ports.mjs -- expo run:android",
     "bundle": "expo export --platform ios --platform android",
     "lint": "biome check",
     "typecheck": "tsc --noEmit",
@@ -22,6 +22,7 @@
     "class-variance-authority": "0.7.1",
     "expo": "57.0.22",
     "expo-constants": "57.0.18",
+    "expo-dev-client": "57.0.19",
     "expo-linking": "57.0.10",
     "expo-router": "57.0.21",
     "expo-secure-store": "57.0.4",

package/templates/mobile/test/features/profile/profile-form.spec.tsx

@@ -36,8 +36,12 @@ describe('ProfileForm', () => {
       }),
     })
 
+    // A mutation left without an observer starts a five-minute garbage-collection timer, and Jest's worker would wait
+    // it out. Infinity schedules none, as TanStack Query's testing guide advises.
+    const queryClient = new QueryClient({ defaultOptions: { mutations: { gcTime: Infinity } } })
+
     await render(
-      <QueryClientProvider client={new QueryClient()}>
+      <QueryClientProvider client={queryClient}>
         <ProfileForm api={api} profile={profile} />
       </QueryClientProvider>,
     )

package/templates/web/README.md

@@ -28,6 +28,11 @@ it spawned, stops them, and frees the port. Anything it did not start is named a
 Open it and you are sent to sign in, because everything but the sign-in and sign-up pages needs a session. Follow
 **Sign up** to create an account; you land on your profile, which you can edit. The API must be running and
 migrated first, or the session check has nothing to answer it.
+<!-- prumo:email -->
+
+Signing up first asks for the 6-digit code that confirms the email. No mail is sent yet: the API writes it to its
+log, in a line starting `[mail] to`, and **Forgot your password?** works the same way.
+<!-- prumo:end-email -->
 
 ## Everyday commands
 

package/templates/workspace/README.md

@@ -29,6 +29,16 @@ If the workspace holds `api` and its database is not set up yet, `pnpm dev` offe
 
 If the workspace holds `web`, open `http://localhost:5173`: you are sent to sign in, and **Sign up** creates an
 account and takes you to your profile. Each app's README says what it needs before it starts.
+<!-- prumo:email -->
+
+Signing up first asks for the 6-digit code that confirms the email. No mail is sent yet: the API writes it to its
+log, in a line starting `[mail] to`, which `pnpm dev` prints with the rest of the API's output.
+<!-- prumo:end-email -->
+<!-- prumo:social -->
+
+A provider's sign-in button answers *That sign-in is not set up yet* until its settings are filled in `apps/api/.env`;
+`.env.example` lists them and says where each one comes from.
+<!-- prumo:end-social -->
 
 ## Conventions