@stjoseph/prumo 0.0.1

package/dist/compose.js

@@ -0,0 +1,222 @@
+import { existsSync } from 'node:fs';
+import { cp, mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { prependProperty, readJsonc, removeWhatBaseDeclares, setJsonc } from "./jsonc.js";
+const CLIENTS = ['web', 'mobile'];
+// One exception to one-version-per-dependency, recorded in DECISIONS.md: stable NativeWind needs Tailwind 3.
+const NAMED_CATALOGS = [{ name: 'tailwind3', dependency: 'tailwindcss', major: '3' }];
+const NOT_COPIED = new Set([
+    'node_modules',
+    'dist',
+    'coverage',
+    '.env',
+    'pnpm-lock.yaml',
+    '.expo',
+    '.next',
+]);
+const NOT_COPIED_SUFFIXES = ['.tsbuildinfo'];
+// The name inside the package, and the name it is restored to. npm deletes a dotted .gitignore from a tarball.
+const PACKAGED_AS = { gitignore: '.gitignore' };
+const CONTRACT_IMPORT = "'@/api-contract'";
+const CONTRACT_PACKAGE = '@app/api-contract';
+function dependencySections(pkg) {
+    return [pkg.dependencies, pkg.devDependencies].filter((section) => section !== undefined);
+}
+async function sourceFiles(directory) {
+    const entries = await readdir(directory, { withFileTypes: true, recursive: true });
+    return entries
+        .filter((entry) => entry.isFile() && /\.tsx?$/.test(entry.name))
+        .map((entry) => join(entry.parentPath, entry.name));
+}
+async function rewriteText(path, change) {
+    await writeFile(path, change(await readFile(path, 'utf8')));
+}
+export async function copyTemplate(source, destination) {
+    await cp(source, destination, {
+        recursive: true,
+        filter: (path) => !relative(source, path)
+            .split('/')
+            .some((part) => NOT_COPIED.has(part) || NOT_COPIED_SUFFIXES.some((suffix) => part.endsWith(suffix))),
+    });
+    // Published, a template's .gitignore is `gitignore`, because npm deletes the dotted name from a tarball.
+    for (const [packaged, restored] of Object.entries(PACKAGED_AS)) {
+        if (existsSync(join(destination, packaged))) {
+            await rename(join(destination, packaged), join(destination, restored));
+        }
+    }
+}
+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 });
+    return destination;
+}
+async function contractFiles(directory) {
+    const files = new Map();
+    for (const file of await sourceFiles(directory)) {
+        files.set(relative(directory, file), await readFile(file, 'utf8'));
+    }
+    return files;
+}
+async function extractContract(target, clients) {
+    const [first, ...others] = clients.map((client) => join(target, 'apps', client));
+    if (first === undefined) {
+        return;
+    }
+    const expected = await contractFiles(join(first, 'src', 'api-contract'));
+    for (const other of others) {
+        const actual = await contractFiles(join(other, 'src', 'api-contract'));
+        const differs = actual.size !== expected.size ||
+            [...expected].some(([file, text]) => actual.get(file) !== text);
+        if (differs) {
+            throw new Error(`${relative(target, other)}/src/api-contract differs from ${relative(target, first)}'s`);
+        }
+        await rm(join(other, 'src', 'api-contract'), { recursive: true });
+    }
+    await rename(join(first, 'src', 'api-contract'), join(target, 'packages', 'api-contract', 'src'));
+    for (const client of [first, ...others]) {
+        for (const directory of ['src', 'test']) {
+            for (const file of await sourceFiles(join(client, directory)).catch(() => [])) {
+                await rewriteText(file, (text) => text.replaceAll(CONTRACT_IMPORT, `'${CONTRACT_PACKAGE}'`));
+            }
+        }
+        await rewriteText(join(client, 'package.json'), (text) => setJsonc(text, ['dependencies', CONTRACT_PACKAGE], 'workspace:*'));
+    }
+}
+function namedCatalogFor(dependency, version) {
+    return NAMED_CATALOGS.find((entry) => entry.dependency === dependency && version.split('.')[0] === entry.major)?.name;
+}
+export function collectCatalog(packages) {
+    const catalogs = { default: {}, named: {} };
+    for (const pkg of packages) {
+        for (const section of dependencySections(pkg)) {
+            for (const [name, version] of Object.entries(section)) {
+                if (version.startsWith('workspace:') || version === 'catalog:') {
+                    continue;
+                }
+                const named = namedCatalogFor(name, version);
+                if (named !== undefined) {
+                    catalogs.named[named] ??= {};
+                }
+                const catalog = named === undefined ? catalogs.default : catalogs.named[named];
+                const existing = catalog[name];
+                if (existing !== undefined && existing !== version) {
+                    throw new Error(`${name} is pinned to both ${existing} and ${version}; a catalog holds one version`);
+                }
+                catalog[name] = version;
+            }
+        }
+    }
+    return catalogs;
+}
+async function adaptAppConfig(target, app) {
+    const packagePath = join(app, 'package.json');
+    let pkg = await readFile(packagePath, 'utf8');
+    const parsed = readJsonc(pkg);
+    pkg = setJsonc(pkg, ['scripts', 'prepare'], undefined);
+    for (const section of ['dependencies', 'devDependencies']) {
+        for (const [name, version] of Object.entries(parsed[section] ?? {})) {
+            if (!version.startsWith('workspace:')) {
+                const named = namedCatalogFor(name, version);
+                pkg = setJsonc(pkg, [section, name], named === undefined ? 'catalog:' : `catalog:${named}`);
+            }
+        }
+    }
+    await writeFile(packagePath, pkg);
+    const tsconfigPath = join(app, 'tsconfig.json');
+    const base = await readFile(join(target, 'tsconfig.base.json'), 'utf8');
+    let tsconfig = removeWhatBaseDeclares(await readFile(tsconfigPath, 'utf8'), base);
+    const inherited = readJsonc(tsconfig).extends;
+    if (inherited === undefined) {
+        tsconfig = prependProperty(tsconfig, 'extends', '../../tsconfig.base.json');
+    }
+    else {
+        tsconfig = setJsonc(tsconfig, ['extends'], ['../../tsconfig.base.json', inherited]);
+    }
+    await writeFile(tsconfigPath, tsconfig);
+    const biomePath = join(app, 'biome.jsonc');
+    const rootBiome = await readFile(join(target, 'biome.jsonc'), 'utf8');
+    const biome = removeWhatBaseDeclares(await readFile(biomePath, 'utf8'), rootBiome);
+    await writeFile(biomePath, prependProperty(biome, 'extends', '//'));
+}
+async function takeBuildApprovals(app) {
+    const path = join(app, 'pnpm-workspace.yaml');
+    const text = await readFile(path, 'utf8').catch(() => undefined);
+    if (text === undefined) {
+        return [];
+    }
+    await rm(path);
+    const lines = text.split('\n');
+    const start = lines.indexOf('allowBuilds:');
+    if (start === -1) {
+        throw new Error(`${path} holds settings other than allowBuilds, which composition does not merge`);
+    }
+    return lines.slice(start + 1).filter((line) => line.startsWith('  '));
+}
+function entriesYaml(catalog, indent) {
+    return Object.keys(catalog)
+        .sort()
+        .map((name) => `${indent}'${name}': ${catalog[name]}`)
+        .join('\n');
+}
+function catalogYaml(catalogs) {
+    const named = Object.entries(catalogs.named)
+        .map(([name, catalog]) => `  ${name}:\n${entriesYaml(catalog, '    ')}`)
+        .join('\n');
+    return `\ncatalog:\n${entriesYaml(catalogs.default, '  ')}\n${named === '' ? '' : `\ncatalogs:\n${named}\n`}`;
+}
+async function assertCatalogCovers(target, catalog) {
+    const manifests = [
+        join(target, 'package.json'),
+        join(target, 'packages', 'api-contract', 'package.json'),
+    ];
+    for (const manifest of manifests) {
+        const pkg = readJsonc(await readFile(manifest, 'utf8'));
+        for (const section of dependencySections(pkg)) {
+            for (const [name, version] of Object.entries(section)) {
+                if (version === 'catalog:' && catalog[name] === undefined) {
+                    throw new Error(`${relative(target, manifest)} needs ${name} from the catalog, and no app pins it`);
+                }
+            }
+        }
+    }
+}
+export async function composeWorkspace({ templates, target, types, mobileScheme = 'app', }) {
+    await mkdir(target, { recursive: true });
+    await copyTemplate(join(templates, 'workspace'), target);
+    const apps = [];
+    for (const type of types) {
+        apps.push(await copyApp(templates, target, type));
+    }
+    const clients = CLIENTS.filter((client) => types.includes(client));
+    if (clients.length > 0) {
+        await extractContract(target, clients);
+    }
+    else {
+        await rm(join(target, 'packages'), { recursive: true, force: true });
+    }
+    if (types.includes('api') && types.includes('mobile')) {
+        await rewriteText(join(target, 'apps', 'api', '.env.example'), (text) => {
+            if (!text.includes('# MOBILE_APP_SCHEME=app\n')) {
+                throw new Error('apps/api/.env.example no longer carries the commented MOBILE_APP_SCHEME line');
+            }
+            return text.replace('# MOBILE_APP_SCHEME=app\n', `MOBILE_APP_SCHEME=${mobileScheme}\n`);
+        });
+    }
+    const manifests = await Promise.all(apps.map(async (app) => readJsonc(await readFile(join(app, 'package.json'), 'utf8'))));
+    const catalogs = collectCatalog(manifests);
+    if (clients.length > 0) {
+        await assertCatalogCovers(target, catalogs.default);
+    }
+    const approvals = [];
+    for (const app of apps) {
+        await adaptAppConfig(target, app);
+        for (const line of await takeBuildApprovals(app)) {
+            if (!approvals.includes(line)) {
+                approvals.push(line);
+            }
+        }
+    }
+    const builds = approvals.length > 0 ? `\nallowBuilds:\n${approvals.join('\n')}\n` : '';
+    await rewriteText(join(target, 'pnpm-workspace.yaml'), (text) => text + catalogYaml(catalogs) + builds);
+}

package/dist/context.js

@@ -0,0 +1,38 @@
+import { cp, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const CLIENTS = ['web', 'mobile', 'site'];
+export function areasFor(answers) {
+    const has = (type) => answers.types.includes(type);
+    return [
+        'core',
+        ...(has('api') ? ['api', 'database'] : []),
+        ...(CLIENTS.some(has) ? ['client'] : []),
+        ...CLIENTS.filter(has),
+        ...(answers.architecture === 'monorepo' ? ['monorepo'] : []),
+        ...(answers.multiTenant ? ['multi-tenancy'] : []),
+    ];
+}
+async function titleOf(path) {
+    const firstLine = (await readFile(path, 'utf8')).split('\n', 1)[0] ?? '';
+    return firstLine.replace(/^#\s*/, '');
+}
+export async function writeContext(knowledge, root, answers) {
+    const prumo = join(root, '.prumo');
+    const lines = [];
+    await mkdir(prumo, { recursive: true });
+    for (const area of areasFor(answers)) {
+        await cp(join(knowledge, area), join(prumo, area), { recursive: true });
+        for (const file of (await readdir(join(prumo, area))).filter((f) => f.endsWith('.md')).sort()) {
+            lines.push(`- [${area}/${file}](${area}/${file}): ${await titleOf(join(prumo, area, file))}`);
+        }
+    }
+    await writeFile(join(prumo, 'INDEX.md'), `# Conventions\n\n${lines.join('\n')}\n`);
+    const config = {
+        types: answers.types,
+        architecture: answers.architecture,
+        multiTenant: answers.multiTenant,
+    };
+    await writeFile(join(prumo, 'config.json'), `${JSON.stringify(config, null, 2)}\n`);
+    await writeFile(join(root, 'AGENTS.md'), `# ${answers.name}\n\nThis project's conventions live in \`.prumo/\`. Read [\`.prumo/INDEX.md\`](.prumo/INDEX.md) before changing how something is done.\n`);
+    await writeFile(join(root, 'CLAUDE.md'), '@AGENTS.md\n');
+}

package/dist/generate.js

@@ -0,0 +1,60 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { composeWorkspace, copyTemplate } from "./compose.js";
+import { writeContext } from "./context.js";
+import { setJsonc } from "./jsonc.js";
+import { schemeFor } from "./names.js";
+async function rewrite(path, change) {
+    await writeFile(path, change(await readFile(path, 'utf8')));
+}
+async function nameProject(root, name) {
+    await rewrite(join(root, 'package.json'), (text) => setJsonc(text, ['name'], name));
+    await rewrite(join(root, 'README.md'), (text) => text.replace(/^# .*$/m, `# ${name}`));
+}
+async function nameMobileApp(app, name) {
+    await rewrite(join(app, 'app.json'), (text) => {
+        let result = setJsonc(text, ['expo', 'name'], name);
+        result = setJsonc(result, ['expo', 'slug'], name);
+        return setJsonc(result, ['expo', 'scheme'], schemeFor(name));
+    });
+}
+function run(command, args, cwd) {
+    const result = spawnSync(command, args, { cwd, stdio: 'inherit' });
+    if (result.status !== 0) {
+        throw new Error(`${command} ${args.join(' ')} failed in ${cwd}`);
+    }
+}
+export async function generate({ templates, knowledge, target, answers, install, }) {
+    if (existsSync(target) && (await readdir(target)).length > 0) {
+        throw new Error(`${target} already exists and is not empty.`);
+    }
+    const [only] = answers.types;
+    if (answers.architecture === 'alone' && only !== undefined) {
+        await copyTemplate(join(templates, only), target);
+        await nameProject(target, answers.name);
+        if (only === 'mobile') {
+            await nameMobileApp(target, answers.name);
+        }
+    }
+    else {
+        await composeWorkspace({
+            templates,
+            target,
+            types: answers.types,
+            mobileScheme: schemeFor(answers.name),
+        });
+        await nameProject(target, answers.name);
+        if (answers.types.includes('mobile')) {
+            await nameMobileApp(join(target, 'apps', 'mobile'), answers.name);
+        }
+    }
+    await writeContext(knowledge, target, answers);
+    run('git', ['init', '--quiet'], target);
+    if (install) {
+        run('pnpm', ['install'], target);
+        // Rewriting the contract import changes import grouping and line length; only the formatter can settle both.
+        run('pnpm', ['exec', 'biome', 'check', '--write'], target);
+    }
+}

package/dist/jsonc.js

@@ -0,0 +1,76 @@
+import { applyEdits, findNodeAtLocation, modify, parse, parseTree, } from 'jsonc-parser';
+const FORMAT = { formattingOptions: { insertSpaces: true, tabSize: 2 } };
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function pathsEqualTo(target, base, path) {
+    if (!isObject(target) || !isObject(base)) {
+        return JSON.stringify(target) === JSON.stringify(base) ? [path] : [];
+    }
+    return Object.keys(target).flatMap((key) => key in base ? pathsEqualTo(target[key], base[key], [...path, key]) : []);
+}
+function emptyObjectPath(value, path) {
+    if (!isObject(value)) {
+        return undefined;
+    }
+    for (const [key, child] of Object.entries(value)) {
+        const found = emptyObjectPath(child, [...path, key]);
+        if (found !== undefined) {
+            return found;
+        }
+    }
+    return Object.keys(value).length === 0 && path.length > 0 ? path : undefined;
+}
+// jsonc-parser's own removal also deletes the comment written above the next property, which here is the
+// one-line reason a rule change must carry. So a property is cut out by its offsets, and nothing after it moves.
+function removeProperty(text, path) {
+    const value = findNodeAtLocation(parseTree(text), path);
+    const property = value?.parent;
+    if (property === undefined) {
+        return text;
+    }
+    let start = property.offset;
+    let end = property.offset + property.length;
+    const after = text.slice(end).match(/^\s*,/);
+    if (after !== null) {
+        end += after[0].length;
+    }
+    else {
+        const before = text.slice(0, start).match(/,\s*$/);
+        if (before !== null) {
+            start -= before[0].length;
+        }
+    }
+    const lineStart = text.lastIndexOf('\n', start - 1) + 1;
+    if (text.slice(lineStart, start).trim() === '') {
+        start = lineStart;
+        const lineEnd = text.indexOf('\n', end);
+        if (lineEnd !== -1 && text.slice(end, lineEnd).trim() === '') {
+            end = lineEnd + 1;
+        }
+    }
+    return text.slice(0, start) + text.slice(end);
+}
+export function readJsonc(text) {
+    return parse(text);
+}
+export function setJsonc(text, path, value) {
+    return value === undefined
+        ? removeProperty(text, path)
+        : applyEdits(text, modify(text, path, value, FORMAT));
+}
+export function prependProperty(text, key, value) {
+    const open = text.indexOf('{');
+    return `${text.slice(0, open + 1)}\n  ${JSON.stringify(key)}: ${JSON.stringify(value)},${text.slice(open + 1)}`;
+}
+export function removeWhatBaseDeclares(text, baseText) {
+    let result = text;
+    for (const path of pathsEqualTo(parse(text), parse(baseText), [])) {
+        result = removeProperty(result, path);
+    }
+    for (let empty = emptyObjectPath(parse(result), []); empty !== undefined;) {
+        result = removeProperty(result, empty);
+        empty = emptyObjectPath(parse(result), []);
+    }
+    return result;
+}

package/dist/names.js

@@ -0,0 +1,10 @@
+const PROJECT_NAME = /^[a-z][a-z0-9-]*$/;
+export function validateProjectName(name) {
+    if (!PROJECT_NAME.test(name)) {
+        return 'Use lowercase letters, digits and hyphens, starting with a letter.';
+    }
+    return undefined;
+}
+export function schemeFor(name) {
+    return name.replaceAll('-', '');
+}

package/dist/questions.js

@@ -0,0 +1,63 @@
+import { validateProjectName } from "./names.js";
+const TYPES = ['api', 'web', 'mobile', 'site'];
+const TENANT_AWARE = ['api', 'web', 'mobile'];
+function missing(flag) {
+    throw new Error(`Missing ${flag}. Outside an interactive terminal every answer must come from a flag.`);
+}
+function parseTypes(value) {
+    const types = value.split(',').map((type) => type.trim());
+    const unknown = types.filter((type) => !TYPES.includes(type));
+    if (unknown.length > 0 || types.length === 0) {
+        throw new Error(`Unknown type: ${unknown.join(', ')}. Choose from ${TYPES.join(', ')}.`);
+    }
+    return [...new Set(types)];
+}
+export async function resolveAnswers(flags, asker) {
+    if (flags.alone && flags.monorepo) {
+        throw new Error('Choose --alone or --monorepo, not both.');
+    }
+    if (flags.multiTenant && flags.singleTenant) {
+        throw new Error('Choose --multi-tenant or --single-tenant, not both.');
+    }
+    const name = flags.name ?? (asker === undefined ? missing('the project name') : await asker.name());
+    const invalid = validateProjectName(name);
+    if (invalid !== undefined) {
+        throw new Error(`Invalid project name "${name}". ${invalid}`);
+    }
+    let types;
+    if (flags.types !== undefined) {
+        types = parseTypes(flags.types);
+    }
+    else if (asker !== undefined) {
+        types = await asker.types();
+    }
+    else {
+        missing('--types');
+    }
+    let architecture = 'alone';
+    if (types.length > 1) {
+        if (flags.alone) {
+            throw new Error('--alone holds a single type; several types make a workspace.');
+        }
+        architecture = 'monorepo';
+    }
+    else if (flags.monorepo) {
+        architecture = 'monorepo';
+    }
+    else if (!flags.alone && asker !== undefined) {
+        architecture = await asker.architecture();
+    }
+    let multiTenant = false;
+    if (types.some((type) => TENANT_AWARE.includes(type))) {
+        if (flags.multiTenant || flags.singleTenant) {
+            multiTenant = flags.multiTenant;
+        }
+        else if (asker !== undefined) {
+            multiTenant = await asker.multiTenant();
+        }
+        else {
+            missing('--multi-tenant or --single-tenant');
+        }
+    }
+    return { name, types, architecture, multiTenant };
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@stjoseph/prumo",
+  "version": "0.0.1",
+  "description": "Scaffolds a TypeScript project and ships it the conventions it follows, in a .prumo/ folder any AI assistant reads.",
+  "keywords": [
+    "scaffolding",
+    "cli",
+    "typescript",
+    "nestjs",
+    "expo",
+    "monorepo",
+    "conventions",
+    "agents",
+    "ai"
+  ],
+  "homepage": "https://github.com/stjosephworks/prumo#readme",
+  "bugs": "https://github.com/stjosephworks/prumo/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stjosephworks/prumo.git",
+    "directory": "cli"
+  },
+  "license": "MIT",
+  "author": "Leonardo Freitas",
+  "type": "module",
+  "bin": {
+    "prumo": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    ".prumo-templates"
+  ],
+  "scripts": {
+    "lint": "biome check",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --dir src",
+    "prumo": "node src/cli.ts",
+    "build": "tsc -p tsconfig.build.json && node scripts/copy-assets.mjs",
+    "prepack": "pnpm build"
+  },
+  "dependencies": {
+    "@clack/prompts": "1.8.1",
+    "jsonc-parser": "3.3.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.13",
+    "@types/node": "24.13.4",
+    "typescript": "6.0.3",
+    "vitest": "4.1.11"
+  },
+  "engines": {
+    "node": ">=22.17.0"
+  }
+}

package/templates/api/.env.example

@@ -0,0 +1,12 @@
+NODE_ENV=development
+PORT=3000
+LOG_LEVEL=info
+
+DATABASE_URL=postgresql://app:app@localhost:5432/app
+AUTH_DATABASE_URL=postgresql://app:app@localhost:5432/app
+
+BETTER_AUTH_SECRET=replace-this-with-at-least-32-characters
+BETTER_AUTH_URL=http://localhost:3000
+WEB_ORIGIN=http://localhost:5173
+# Set only when a mobile app talks to this API; it enables Better Auth's Expo plugin.
+# MOBILE_APP_SCHEME=app

package/templates/api/.githooks/install.mjs

@@ -0,0 +1,18 @@
+import { execFileSync } from 'node:child_process'
+
+function insideRepository() {
+  try {
+    execFileSync('git', ['rev-parse', '--git-dir'], { stdio: 'ignore' })
+    return true
+  } catch (error) {
+    // No git, or no repository: an install from an archive or inside a container, where hooks have no use.
+    if (error.code === 'ENOENT' || error.status === 128) {
+      return false
+    }
+    throw error
+  }
+}
+
+if (insideRepository()) {
+  execFileSync('git', ['config', 'core.hooksPath', '.githooks'], { stdio: 'inherit' })
+}

package/templates/api/.githooks/pre-commit

@@ -0,0 +1,2 @@
+#!/bin/sh
+pnpm biome check --staged --write

package/templates/api/.githooks/pre-push

@@ -0,0 +1,2 @@
+#!/bin/sh
+pnpm typecheck

package/templates/api/README.md

@@ -0,0 +1,35 @@
+# api
+
+## Requirements
+
+Node 22.17 or later, pnpm, and Docker.
+
+## Running it
+
+```sh
+pnpm install
+cp .env.example .env        # then replace BETTER_AUTH_SECRET with 32 or more random characters
+docker compose up -d --wait
+pnpm db:migrate
+pnpm start:dev
+```
+
+The API listens on `http://localhost:3000`. Outside production, its documentation is at `/api/docs`.
+
+`pnpm db:migrate` builds first, then runs Better Auth's migrations and then the application's. Before
+migrating, Better Auth logs `Database schema mismatch` because its tables do not exist yet; the migration
+still completes.
+
+## Everyday commands
+
+| Command | What it does |
+|---|---|
+| `pnpm test` | Runs the suite against a throwaway Postgres; Docker must be running |
+| `pnpm lint` | Biome |
+| `pnpm typecheck` | `tsc --noEmit`, also run before every push |
+| `pnpm db:migration:create` | Generates a migration from the entity diff, to be read and edited before committing |
+
+## Conventions
+
+The rules this project follows live in `.prumo/`, and `AGENTS.md` points to them. Read those before
+changing how something is done.

package/templates/api/biome.jsonc

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.13/schema.json",
+  "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
+  "files": { "includes": ["**", "!dist", "!coverage", "!migrations"] },
+  "formatter": { "indentStyle": "space", "indentWidth": 2, "lineWidth": 100 },
+  "linter": {
+    "rules": {
+      "preset": "recommended",
+      // Nest injects by the emitted constructor type; `import type` erases it and breaks injection silently.
+      "style": { "useImportType": "off" }
+    }
+  },
+  "javascript": {
+    "formatter": { "quoteStyle": "single", "semicolons": "asNeeded" },
+    // Nest decorates constructor and handler parameters; Biome cannot parse those without this.
+    "parser": { "unsafeParameterDecoratorsEnabled": true }
+  }
+}

package/templates/api/docker/init/01-auth-schema.sql

@@ -0,0 +1 @@
+CREATE SCHEMA IF NOT EXISTS auth;

package/templates/api/docker-compose.yml

@@ -0,0 +1,20 @@
+services:
+  postgres:
+    image: postgres:18-alpine
+    environment:
+      POSTGRES_USER: app
+      POSTGRES_PASSWORD: app
+      POSTGRES_DB: app
+    ports:
+      - '5432:5432'
+    volumes:
+      - postgres:/var/lib/postgresql
+      - ./docker/init:/docker-entrypoint-initdb.d:ro
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U app']
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+volumes:
+  postgres:

package/templates/api/gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+coverage
+*.tsbuildinfo
+.env

package/templates/api/migrations/Migration20260914123239_create_profile.ts

@@ -0,0 +1,13 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260914123239_create_profile extends Migration {
+
+  override name = 'Migration20260914123239_create_profile';
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "profile" ("id" uuid not null default uuidv7(), "user_id" uuid not null, "display_name" text not null, "locale" text not null default 'en', "timezone" text not null default 'UTC', "created_at" timestamptz not null default now(), "updated_at" timestamptz not null default now(), primary key ("id"));`);
+    this.addSql(`alter table "profile" add constraint "profile_user_id_unique" unique ("user_id");`);
+    this.addSql(`alter table "profile" add constraint "profile_user_id_foreign" foreign key ("user_id") references "auth"."user" ("id") on delete restrict;`);
+  }
+
+}