@stjoseph/prumo 0.5.0 → 0.6.0

package/.prumo-templates/api/auth.md

@@ -20,7 +20,7 @@ still verify the password against a decoy hash, and answer exactly as for a wron
 Give the web its tokens in `httpOnly`, `SameSite=Lax` cookies: the access cookie on `/`, the refresh cookie only
 on `/api/auth/refresh`, both `Secure` when `API_URL` is https. Give a native client its tokens in the body, and
 only when it sends `X-Auth-Transport: bearer`; it then sends `Authorization: Bearer`. Refuse with 403 any
-request that changes state, carries a cookie and no bearer, and does not come from `WEB_ORIGIN`.
+request that changes state, carries a cookie and no bearer, and does not come from an origin in `WEB_ORIGIN`, the comma-separated list of the web apps.
 
 Every route is protected by the global `preHandler` hook in `auth.hook.ts`. Mark a route that needs no session
 with `config: { public: true }`; that means only *do not answer 401*, and the token is still read. Read the

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/.prumo-templates/mcp/server.md

@@ -25,7 +25,7 @@ authorization profile:
 - Identify a client by its metadata document (CIMD) only. Do not enable dynamic client registration.
 - Check the client and its redirect URI, by exact match, before any error may be redirected.
 - Require PKCE with `S256`, and a `resource` equal to `mcpResource(env)`, which becomes the token's audience.
-- Send the browser to the web app's `/consent`. Show the client's name, the host of its `client_id` and the
+- Send the browser to `/consent` on the first web app in `WEB_ORIGIN`. Show the client's name, the host of its `client_id` and the
   host of its redirect URI, and warn when that redirect returns to this device.
 - Return the code with `iss` (RFC 9207), and spend it once: a code presented twice revokes the session its
   first exchange started.

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

@@ -5,7 +5,10 @@
 Put deployable things in `apps/` and shared code in `packages/`.
 
 Name an app directory after its type (`apps/api`, `apps/web`, `apps/mobile`, `apps/site`), never after
-the product.
+the product. A second web or site, or an app renamed on purpose, is named for its role (`apps/backoffice`,
+`apps/blog`), still never after the product. The directory, the package and the root script share that name, and
+`.prumo/config.json` lists every app with its type. Only `web` and `site` repeat; a workspace holds one `api` and
+one `mobile`.
 
 Keep one package from the start: the integration layer between the clients and the API. It holds URL
 construction, the `ApiError` parsing, the hand-written contract types and the query factories.
@@ -58,6 +61,7 @@ Layout:
 
 ```
 ✅  apps/api  apps/web  packages/api-contract
+✅  apps/api  apps/web  apps/backoffice  packages/api-contract
 ❌  apps/acme-backend  packages/shared
 ```
 

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

@@ -9,7 +9,8 @@ and `test` as well, each running through `pnpm -r`.
 **Every app answers to `dev`.** When a framework names its development command differently, keep its name and
 alias it: `"dev": "pnpm start:dev"` in the API, `"dev": "pnpm start"` in mobile.
 
-**Give every app its own port.** The API holds 3000, so the site runs on 3200.
+**Give every app its own port.** The API holds 3000, so the site runs on 3200. A second app of a type takes the
+next port of that type: a second web 5174, a second site 3201.
 
 Keep compiler options in `tsconfig.base.json` at the workspace root. Extend it by relative path from each
 app and package, overriding only what differs.
@@ -82,8 +83,9 @@ Extending the base:
 **The hook.** Pre-push runs the root `typecheck`, so a type error in any package stops the push.
 
 **Review only.** That a new app extends the base rather than copying it, answers to `dev`, runs on a port no
-other app uses, and has a root script named after it. A missing `dev` fails nothing: `pnpm -r` skips a package
-without the script, so the app simply does not start.
+other app uses, has a root script named after it, and is listed in `.prumo/config.json`, where `scripts/ports.mjs`
+finds it. `prumo add <type> [name]` writes all of it; an app added by hand needs the same. A missing `dev` fails
+nothing: `pnpm -r` skips a package without the script, so the app simply does not start.
 
 **The reversal condition, stated so it is measurable rather than a feeling:** without caching,
 `pnpm -r typecheck` runs `tsc` in every package from scratch every time. Turborepo belongs on the table the

package/.prumo-templates/social/sign-in.md

@@ -12,7 +12,8 @@ in the `social_sign_in` cookie that the callback must present. Use PKCE wherever
 it, and a nonce always. Turn Apple's `form_post` callback into a redirect to the same address, so the cookie
 comes with it.
 
-Return the web to the path it asked for, only a path on the web app, with session cookies. Return a mobile app
+Return the web to the path it asked for, only a path, with session cookies, on the web app that started: it sends
+its `origin`, which must be in `WEB_ORIGIN`, and the `social_sign_in` cookie carries it to the callback. Return a mobile app
 to `MOBILE_APP_SCHEME://social` with a one-time code it exchanges at `/api/auth/social/exchange` for its tokens,
 within two minutes. A mobile app opens the trip with `expo-web-browser`'s `openAuthSessionAsync`.
 

package/README.md

@@ -60,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
@@ -74,6 +76,7 @@ npx @stjoseph/prumo new my-api --types api --alone --single-tenant --email
 | Flag | What it answers |
 |---|---|
 | `--types api,web,mobile,site` | What the project contains. More than one type makes a workspace |
+| `--app <name>=<type>` | Advanced, repeatable: an app with a name of its own, as `--app backoffice=web`. A type left out of `--types` and given here is renamed. Only `web` and `site` repeat, and an `--app` makes a workspace |
 | `--alone` or `--monorepo` | How a single type is laid out, so one type needs one of them. Several types always make a workspace and refuse `--alone` |
 | `--multi-tenant` or `--single-tenant` | Whether the application serves several tenants. Multi-tenant ships the `multi-tenancy` conventions; the generated code itself is not tenant-aware yet |
 | `--mcp` or `--no-mcp` | With an api and a web: whether AI assistants reach the API through MCP, signed in as the user |
@@ -86,6 +89,7 @@ npx @stjoseph/prumo new my-api --types api --alone --single-tenant --email
 | Command | What it does |
 |---|---|
 | `prumo new [name \| .]` | Generates a project |
+| `prumo add <type> [name]` | Inside a workspace: adds an app, named after its type unless a name is given, as `prumo add web backoffice`. It gets the next free port, the shared contract, the API's trust when it is a web app, and the `.prumo/` areas it needs. Only the Prumo version that generated the project adds to it |
 | `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, and that Docker runs Linux containers |
@@ -106,7 +110,7 @@ is asked, and the exit code is 0 only when `ok` is true.
 | `site` | Next on the App Router, static by default, for pages that have to be indexed |
 
 One type produces that project on its own. Several produce a pnpm workspace: each application under
-`apps/`, the wire contract shared through `packages/api-contract` so a change on one side breaks the
+`apps/`, named after its type unless it was named on purpose, the wire contract shared through `packages/api-contract` so a change on one side breaks the
 other at typecheck, and one version per dependency held in a catalog.
 
 Every template is committed here in full, and none of them is generated by calling somebody else's
@@ -138,6 +142,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
 
@@ -145,6 +150,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/add.js

@@ -0,0 +1,219 @@
+import { existsSync } from 'node:fs';
+import { readFile, rm, writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { appsOf, appsOfType, PORTS, typesOf, validateApps } from "./apps.js";
+import { adaptAppConfig, CLIENTS, collectCatalog, copyApp, copyTemplate, extractContract, joinContract, rootDevPrefix, takeBuildApprovals, } from "./compose.js";
+import { areasFor, growContext } from "./context.js";
+import { findProjectRoot, readConfig } from "./database.js";
+import { applyFeatures, enabledFor } from "./features.js";
+import { nameCompose, nameMobileApp, run, settleMobileScheme, watchInterrupt, writeLocalEnv, } from "./generate.js";
+import { readJsonc, setJsonc } from "./jsonc.js";
+import { schemeFor } from "./names.js";
+import { CliError } from "./output.js";
+import { cliVersion } from "./version.js";
+import { addApprovals, addToCatalogs } from "./workspace-yaml.js";
+// What the run changed, so a failure halfway puts the project back as it found it: each file it rewrote returns
+// to what it held, and each it created goes.
+class Journal {
+    before = new Map();
+    async keep(path) {
+        if (!this.before.has(path)) {
+            this.before.set(path, existsSync(path) ? await readFile(path, 'utf8') : null);
+        }
+    }
+    creates(path) {
+        if (!this.before.has(path)) {
+            this.before.set(path, null);
+        }
+    }
+    async undo() {
+        for (const [path, text] of [...this.before].reverse()) {
+            if (text === null) {
+                await rm(path, { recursive: true, force: true });
+            }
+            else {
+                await writeFile(path, text);
+            }
+        }
+    }
+}
+function envLine(text, key) {
+    return new RegExp(`^${key}=(.*)$`, 'm').exec(text)?.[1]?.trim();
+}
+function withEnvLine(text, key, value) {
+    return text.replace(new RegExp(`^${key}=.*$`, 'm'), `${key}=${value}`);
+}
+async function readEnv(directory) {
+    for (const file of ['.env', '.env.example']) {
+        const text = await readFile(join(directory, file), 'utf8').catch(() => undefined);
+        if (text !== undefined) {
+            return text;
+        }
+    }
+    return '';
+}
+const SCHEME_BLOCK = (scheme) => `# The mobile app's scheme, as in app.json: where it is sent back after signing in with a provider.\nMOBILE_APP_SCHEME=${scheme}\n`;
+export async function addApp({ templates, knowledge, cwd, type, name = type, install, childOutput = 'inherit', }) {
+    const root = findProjectRoot(cwd);
+    const config = readConfig(root);
+    if (config.architecture !== 'monorepo') {
+        throw new CliError('not_a_workspace', 'This project is one app, laid out alone. `prumo add` grows a workspace.');
+    }
+    // The app is copied from this CLI's templates, so only the version that wrote the project gives it the
+    // dependencies its catalog holds and an API that trusts several web apps.
+    const wrote = config.prumo;
+    const running = cliVersion();
+    if (wrote !== running) {
+        const [major = 0, minor = 0] = (wrote ?? '0.0').split('.').map(Number);
+        throw new CliError('version_mismatch', major === 0 && minor < 6
+            ? `This project was generated by Prumo ${wrote ?? 'before 0.1.1'}, and \`prumo add\` exists from 0.6.0.`
+            : `This project was generated by Prumo ${wrote}, and this is ${running}. Run \`npx @stjoseph/prumo@${wrote} add ${type} ${name}\`.`);
+    }
+    const project = readJsonc(await readFile(join(root, 'package.json'), 'utf8')).name;
+    const apps = appsOf(config);
+    const app = { name, type };
+    const next = [...apps, app];
+    validateApps(next, project);
+    const directory = join(root, 'apps', name);
+    if (existsSync(directory)) {
+        throw new CliError('target_not_empty', `${relative(root, directory)} already exists.`);
+    }
+    const answers = { ...config, name: project, types: typesOf(next), apps: next };
+    const journal = new Journal();
+    const unwatch = watchInterrupt();
+    try {
+        const result = await write({ templates, knowledge, root, project, apps, app, answers, journal });
+        if (install) {
+            await journal.keep(join(root, 'pnpm-lock.yaml'));
+            run('pnpm', ['install'], root, childOutput);
+            // Only what this run wrote: the rest of the workspace is the team's, formatted as they left it.
+            run('pnpm', [
+                'exec',
+                'biome',
+                'check',
+                '--write',
+                ...result.written.map((path) => relative(root, path)),
+            ], root, childOutput);
+            if (type === 'web') {
+                run('pnpm', ['exec', 'tsr', 'generate'], directory, childOutput);
+            }
+        }
+        return { app, directory, port: result.port, areas: result.areas, installed: install };
+    }
+    catch (error) {
+        await journal.undo();
+        throw error;
+    }
+    finally {
+        unwatch();
+    }
+}
+async function write({ templates, knowledge, root, project, apps, app, answers, journal, }) {
+    const at = (one) => join(root, 'apps', one.name);
+    const directory = at(app);
+    const written = [directory];
+    const [api] = appsOfType(apps, 'api');
+    const rewrite = async (path, change) => {
+        await journal.keep(path);
+        await writeFile(path, change(await readFile(path, 'utf8')));
+    };
+    journal.creates(directory);
+    await copyApp(templates, root, app);
+    await applyFeatures(directory, app.type, enabledFor(answers));
+    // The first port of its type that no app of the workspace holds, as each one's .env says today.
+    const { key, from } = PORTS[app.type];
+    const held = new Set();
+    for (const other of apps) {
+        const port = envLine(await readEnv(at(other)), PORTS[other.type].key);
+        held.add(Number(port ?? PORTS[other.type].from));
+    }
+    let port = from;
+    while (held.has(port)) {
+        port += 1;
+    }
+    await rewrite(join(directory, '.env.example'), (text) => withEnvLine(text, key, String(port)));
+    if (app.type === 'site') {
+        await rewrite(join(directory, 'package.json'), (text) => {
+            const start = readJsonc(text).scripts.start;
+            return setJsonc(text, ['scripts', 'start'], start.replace(`--port ${from}`, `--port ${port}`));
+        });
+    }
+    if (CLIENTS.includes(app.type)) {
+        const contract = join(root, 'packages', 'api-contract');
+        if (existsSync(contract)) {
+            await joinContract(directory);
+        }
+        else {
+            journal.creates(contract);
+            await copyTemplate(join(templates, 'workspace', 'packages', 'api-contract'), contract);
+            await extractContract(root, [app]);
+            written.push(contract);
+        }
+    }
+    // Before the app's own manifest becomes `catalog:`, which is what says the versions it needs.
+    const manifest = readJsonc(await readFile(join(directory, 'package.json'), 'utf8'));
+    const workspaceYaml = join(root, 'pnpm-workspace.yaml');
+    await rewrite(workspaceYaml, (text) => addToCatalogs(text, collectCatalog([manifest])));
+    await adaptAppConfig(root, directory);
+    const approvals = await takeBuildApprovals(directory);
+    await rewrite(workspaceYaml, (text) => addApprovals(text, approvals));
+    await rewrite(join(root, 'package.json'), (text) => {
+        let pkg = setJsonc(text, ['scripts', app.name], `pnpm --filter ${app.name} dev`);
+        if (app.type === 'api') {
+            const dev = readJsonc(pkg).scripts.dev;
+            pkg = setJsonc(pkg, ['scripts', 'dev'], `${rootDevPrefix(app.name)}${dev}`);
+        }
+        return pkg;
+    });
+    await writeLocalEnv(directory, app.type);
+    const origin = `http://localhost:${port}`;
+    const webs = appsOfType(apps, 'web');
+    const mobile = appsOfType(apps, 'mobile')[0];
+    for (const file of ['.env.example', '.env']) {
+        // A new web app is one more origin for the API to trust.
+        if (app.type === 'web' && api !== undefined && existsSync(join(at(api), file))) {
+            await rewrite(join(at(api), file), (text) => {
+                const list = (envLine(text, 'WEB_ORIGIN') ?? '').split(',').filter((entry) => entry !== '');
+                return withEnvLine(text, 'WEB_ORIGIN', [...list, origin].join(','));
+            });
+        }
+        // A new API trusts the web apps there already, on the ports they hold.
+        if (app.type === 'api' && webs.length > 0) {
+            const origins = [];
+            for (const web of webs) {
+                origins.push(`http://localhost:${envLine(await readEnv(at(web)), 'WEB_PORT') ?? 5173}`);
+            }
+            await rewrite(join(directory, file), (text) => withEnvLine(text, 'WEB_ORIGIN', origins.join(',')));
+        }
+        // A mobile app signing in with a provider is sent back by its scheme, which the API was given none of.
+        if (app.type === 'mobile' &&
+            api !== undefined &&
+            answers.social.length > 0 &&
+            existsSync(join(at(api), file))) {
+            await rewrite(join(at(api), file), (text) => /^MOBILE_APP_SCHEME=/m.test(text)
+                ? text
+                : text.replace(/^(WEB_ORIGIN=.*\n)/m, `$1${SCHEME_BLOCK(schemeFor(project))}`));
+        }
+    }
+    // A client points at the API where it answers now, which may not be where the template said.
+    const apiUrl = api === undefined ? undefined : envLine(await readEnv(at(api)), 'API_URL');
+    const clientKey = { web: 'VITE_API_URL', mobile: 'EXPO_PUBLIC_API_URL' }[app.type];
+    if (apiUrl !== undefined && clientKey !== undefined) {
+        await rewrite(join(directory, '.env'), (text) => withEnvLine(text, clientKey, apiUrl));
+    }
+    if (app.type === 'api') {
+        await nameCompose(directory, project);
+        await settleMobileScheme(directory, mobile === undefined ? null : schemeFor(project));
+    }
+    if (app.type === 'mobile') {
+        await nameMobileApp(directory, project);
+    }
+    const prumo = join(root, '.prumo');
+    for (const area of areasFor(answers).filter((each) => !existsSync(join(prumo, each)))) {
+        journal.creates(join(prumo, area));
+    }
+    await journal.keep(join(prumo, 'INDEX.md'));
+    await journal.keep(join(prumo, 'config.json'));
+    const areas = await growContext(knowledge, root, answers);
+    return { port, areas, written: [...written, join(prumo, 'config.json')] };
+}

package/dist/apps.js

@@ -0,0 +1,205 @@
+import { join } from 'node:path';
+import { CliError } from "./output.js";
+export const TYPES = ['api', 'web', 'mobile', 'site'];
+// A second api would need its own database, contract and clients to point at it, and a second mobile app its own
+// scheme for the API to send it back to; neither is offered.
+export const REPEATABLE = ['web', 'site'];
+const APP_NAME = /^[a-z][a-z0-9-]*$/;
+// The workspace root's own scripts, which an app's script of the same name would overwrite.
+export const ROOT_SCRIPTS = ['dev', 'lint', 'typecheck', 'test', 'prepare'];
+// `pnpm <name>` runs the root script only when pnpm has no command of that name. The commands and aliases of pnpm
+// 10.26, the floor, and of 12.3.
+const PNPM_COMMANDS = [
+    't',
+    'access',
+    'init',
+    'recursive',
+    'multi',
+    'm',
+    'add',
+    'install',
+    'i',
+    'install-test',
+    'it',
+    'update',
+    'up',
+    'upgrade',
+    'outdated',
+    'audit',
+    'change',
+    'version',
+    'lane',
+    'bugs',
+    'issues',
+    'list',
+    'ls',
+    'll',
+    'la',
+    'licenses',
+    'licences',
+    'why',
+    'view',
+    'info',
+    'show',
+    'v',
+    'sbom',
+    'whoami',
+    'deprecate',
+    'undeprecate',
+    'unpublish',
+    'star',
+    'unstar',
+    'stars',
+    'dist-tag',
+    'dist-tags',
+    'ping',
+    'doctor',
+    'search',
+    's',
+    'se',
+    'find',
+    'rebuild',
+    'rb',
+    'pack',
+    'publish',
+    'stage',
+    'remove',
+    'uninstall',
+    'rm',
+    'un',
+    'uni',
+    'patch',
+    'patch-commit',
+    'patch-remove',
+    'peers',
+    'set-script',
+    'ss',
+    'run',
+    'exec',
+    'dlx',
+    'create',
+    'completion',
+    'start',
+    'stop',
+    'restart',
+    'find-hash',
+    'runtime',
+    'rt',
+    'env',
+    'shim',
+    'bin',
+    'clean',
+    'purge',
+    'ci',
+    'clean-install',
+    'ic',
+    'install-clean',
+    'root',
+    'prefix',
+    'config',
+    'c',
+    'get',
+    'set',
+    'pkg',
+    'pack-app',
+    'store',
+    'cache',
+    'cat-file',
+    'cat-index',
+    'ignored-builds',
+    'approve-builds',
+    'link',
+    'ln',
+    'import',
+    'dedupe',
+    'deploy',
+    'prune',
+    'fetch',
+    'unlink',
+    'dislink',
+    'docs',
+    'home',
+    'repo',
+    'self-update',
+    'setup',
+    'login',
+    'adduser',
+    'team',
+    'owner',
+    'owners',
+    'logout',
+    'with',
+    'edit',
+    'profile',
+    'token',
+    'xmas',
+    'help',
+];
+export const RESERVED_APP_NAMES = [...ROOT_SCRIPTS, ...PNPM_COMMANDS];
+// Where an app of a type keeps its port and the first one it takes; a second app of the type takes the next.
+export const PORTS = {
+    api: { key: 'PORT', from: 3000 },
+    web: { key: 'WEB_PORT', from: 5173 },
+    site: { key: 'SITE_PORT', from: 3200 },
+    mobile: { key: 'METRO_PORT', from: 8081 },
+};
+export function defaultApps(types) {
+    return types.map((type) => ({ name: type, type }));
+}
+export function typesOf(apps) {
+    return [...new Set(apps.map((app) => app.type))];
+}
+export function appsOfType(apps, type) {
+    return apps.filter((app) => app.type === type);
+}
+// `name=type`, as `--app backoffice=web` writes it.
+export function parseApp(value) {
+    const [name = '', type = '', ...rest] = value.split('=').map((part) => part.trim());
+    if (rest.length > 0 || name === '' || type === '') {
+        throw new CliError('invalid_app', `--app takes <name>=<type>, as in backoffice=web; got "${value}".`);
+    }
+    if (!TYPES.includes(type)) {
+        throw new CliError('invalid_app', `Unknown type in --app ${value}: ${type}. Choose from ${TYPES.join(', ')}.`);
+    }
+    return { name, type: type };
+}
+// Why a name cannot name an app beside the others, or undefined when it can.
+export function appNameProblem(name, others, project) {
+    if (!APP_NAME.test(name)) {
+        return 'Use lowercase letters, digits and hyphens, starting with a letter.';
+    }
+    if (RESERVED_APP_NAMES.includes(name)) {
+        return `"${name}" is a pnpm command or a root script, so \`pnpm ${name}\` would never start the app.`;
+    }
+    if (name === project) {
+        return 'That is the project’s name, which its root package already takes.';
+    }
+    if (others.some((other) => other.name === name)) {
+        return `Another app is already named "${name}".`;
+    }
+    return undefined;
+}
+export function validateApps(apps, project) {
+    apps.forEach((app, index) => {
+        const problem = appNameProblem(app.name, apps.slice(0, index), project);
+        if (problem !== undefined) {
+            throw new CliError('invalid_app', `Invalid app name "${app.name}". ${problem}`);
+        }
+    });
+    for (const type of TYPES.filter((each) => !REPEATABLE.includes(each))) {
+        if (appsOfType(apps, type).length > 1) {
+            throw new CliError('invalid_app', `A workspace holds one ${type}; only ${REPEATABLE.join(' and ')} may repeat.`);
+        }
+    }
+}
+// Each app's port: the type's first, then the next for each further app of that type.
+export function portOf(apps, app) {
+    return PORTS[app.type].from + appsOfType(apps, app.type).indexOf(app);
+}
+export function appDirectory(root, architecture, app) {
+    return architecture === 'alone' ? root : join(root, 'apps', app.name);
+}
+// The apps a project's config describes. One written before apps had names holds one app per type, named after it.
+export function appsOf(config) {
+    return config.apps ?? defaultApps(config.types);
+}

package/dist/asker.js

@@ -1,6 +1,8 @@
 import * as prompt from '@clack/prompts';
+import { appNameProblem, REPEATABLE } from "./apps.js";
 import { SOCIAL_PROVIDERS } from "./features.js";
 const TYPES = ['api', 'web', 'mobile', 'site'];
+const DONE = 'done';
 function answered(value) {
     if (prompt.isCancel(value)) {
         prompt.cancel('Nothing was generated.');
@@ -24,6 +26,41 @@ export function terminalAsker(validateName) {
             ],
             initialValue: 'alone',
         })),
+        apps: async (defaults, project) => {
+            const advanced = answered(await prompt.confirm({
+                message: 'Advanced: rename the apps, or add another web or site?',
+                initialValue: false,
+            }));
+            if (!advanced) {
+                return defaults;
+            }
+            const apps = [];
+            const named = async (type, initialValue) => {
+                const name = answered(await prompt.text({
+                    message: `Name of the ${type} app`,
+                    initialValue,
+                    validate: (value) => appNameProblem(value ?? '', apps, project),
+                }));
+                apps.push({ name, type });
+            };
+            for (const app of defaults) {
+                await named(app.type, app.name);
+            }
+            while (true) {
+                const type = answered(await prompt.select({
+                    message: 'Add another app?',
+                    options: [
+                        { value: DONE, label: 'no, that is all' },
+                        ...REPEATABLE.map((each) => ({ value: each, label: each })),
+                    ],
+                    initialValue: DONE,
+                }));
+                if (type === DONE) {
+                    return apps;
+                }
+                await named(type, '');
+            }
+        },
         multiTenant: async () => answered(await prompt.confirm({ message: 'Is it multi-tenant?', initialValue: false })),
         mcp: async () => answered(await prompt.confirm({
             message: 'Let AI assistants use the API through MCP, signed in as the user?',