@cmpose/core 0.3.0 → 0.5.0

package/README.md

@@ -2,4 +2,4 @@
 
 The cmpose generator library: it turns the pinned Compose Multiplatform template into a new project (validation, package and name rewrites, optional features and modules). See the README at the root of the cmpose repository for usage and development.
 
-It also generates Unity mobile games from the pinned game template: `game.validateGame`, `game.generateGame` and `game.describeGame`.
+It also generates Unity mobile games from the pinned game template: `game.validateGame`, `game.generateGame` and `game.describeGame` (`describeGame({ themes: await game.readThemes(templateDir) })` adds the template's theme families).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmpose/core",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "cmpose project generator core (Compose Multiplatform)",
   "license": "MIT",
   "repository": {

package/src/backend/contract.js

@@ -0,0 +1,39 @@
+'use strict';
+const { hashContract } = require('../contract');
+
+// The Ktor backend generator's contract: what the backend_* tools accept. Published facts feed contractVersion.
+const BACKEND_SCHEMA = Object.freeze({
+    appName: Object.freeze({
+        pattern: '^[a-z][a-z0-9-]{1,30}$',
+        // the server's own route prefixes
+        reserved: Object.freeze(['api', 'health', 'admin', 'static']),
+        // the shared server's own services, which an app's compose service and nginx location must not shadow
+        infrastructure: Object.freeze(['postgres', 'nginx', 'proxy', 'db', 'redis']),
+        // PostgreSQL's own databases and schema, and its pg_ prefix for roles (matched on the database name)
+        postgresReserved: Object.freeze(['public', 'template0', 'template1', 'postgres']),
+        postgresPrefix: 'pg_',
+        // PostgreSQL's reserved key words (both reserved columns of the key word appendix): the database name never is one
+        sqlKeywords: Object.freeze([
+            'all', 'analyse', 'analyze', 'and', 'any', 'array', 'as', 'asc', 'asymmetric', 'authorization', 'binary', 'both',
+            'case', 'cast', 'check', 'collate', 'collation', 'column', 'concurrently', 'constraint', 'create', 'cross',
+            'current_catalog', 'current_date', 'current_role', 'current_schema', 'current_time', 'current_timestamp',
+            'current_user', 'default', 'deferrable', 'desc', 'distinct', 'do', 'else', 'end', 'except', 'false', 'fetch',
+            'for', 'foreign', 'freeze', 'from', 'full', 'grant', 'group', 'having', 'ilike', 'in', 'initially', 'inner',
+            'intersect', 'into', 'is', 'isnull', 'join', 'lateral', 'leading', 'left', 'like', 'limit', 'localtime',
+            'localtimestamp', 'natural', 'not', 'notnull', 'null', 'offset', 'on', 'only', 'or', 'order', 'outer',
+            'overlaps', 'placing', 'primary', 'references', 'returning', 'right', 'select', 'session_user', 'similar',
+            'some', 'symmetric', 'system_user', 'table', 'tablesample', 'then', 'to', 'trailing', 'true', 'union', 'unique',
+            'user', 'using', 'variadic', 'verbose', 'when', 'where', 'window', 'with'
+        ])
+    }),
+    options: Object.freeze({ sharing: Object.freeze({ type: 'boolean', default: false }) }),
+    // The template's own names, which the generator renames
+    identity: Object.freeze({ package: 'io.cmpose.backendtemplate', appName: 'cmpose-app', projectName: 'Cmpose Backend' }),
+    anatomy: Object.freeze({ localTask: 'runLocal', localPort: 18001, deployDir: 'deploy' })
+});
+
+function backendContractVersion() {
+    return hashContract(BACKEND_SCHEMA);
+}
+
+module.exports = { BACKEND_SCHEMA, backendContractVersion };

package/src/backend/describe.js

@@ -0,0 +1,73 @@
+'use strict';
+const pins = require('../pins');
+const { BACKEND_SCHEMA: S, backendContractVersion } = require('./contract');
+
+/** What the Ktor backend generator offers, plus the rules an AI client follows when it writes code in the project */
+function describeBackend() {
+    const port = S.anatomy.localPort;
+    return {
+        contractVersion: backendContractVersion(),
+        templateRef: pins.backend.ref,
+        template: pins.backend,
+        options: {
+            sharing: {
+                type: S.options.sharing.type,
+                default: S.options.sharing.default,
+                description: 'Spaces shared between users, with roles (viewer, editor, owner) and invitations. Off: every row belongs to one user.'
+            }
+        },
+        appNameRules: {
+            pattern: S.appName.pattern,
+            reserved: S.appName.reserved.slice(),
+            infrastructure: S.appName.infrastructure.slice(),
+            postgresReserved: S.appName.postgresReserved.slice(),
+            postgresPrefix: 'pg-',
+            sqlKeywords: S.appName.sqlKeywords.slice(),
+            databaseName: 'appName with - replaced by _ (database and database user)'
+        },
+        anatomy: {
+            stack: 'Kotlin on JVM 21, Ktor, Exposed, Flyway, PostgreSQL, HikariCP; Firebase ID tokens verified on the server',
+            paths: {
+                'src/main/kotlin/<package>/config': 'AppConfig: every setting, read from the environment',
+                'src/main/kotlin/<package>/plugins': 'errors, security headers, CORS, body limits, rate limits, request ids, client version',
+                'src/main/kotlin/<package>/auth': 'token verification and requireUser()',
+                'src/main/kotlin/<package>/users': 'GET and DELETE /api/v1/me',
+                'src/main/kotlin/<package>/files': 'uploads and downloads',
+                'src/main/kotlin/<package>/feature/sample': 'the sample feature (/api/v1/items): the shape to copy',
+                'src/main/kotlin/<package>/sharing': 'spaces, roles and invitations (sharing only)',
+                'src/main/kotlin/<package>/openapi': 'the API description, served at /api/v1/openapi.json',
+                'src/main/resources/db/migration': 'Flyway migrations (V<n>__<name>.sql)',
+                'src/local/kotlin': 'the local runner (embedded PostgreSQL)',
+                [S.anatomy.deployDir + '/']: 'Dockerfile, compose fragment, nginx location, database script, .env.example'
+            },
+            routes: { api: '/api/v1', liveness: '/health', readiness: '/ready', openapi: '/api/v1/openapi.json' },
+            containerPort: 8080,
+            localPort: port,
+            requiredEnv: ['DATABASE_URL', 'DATABASE_USER', 'DATABASE_PASSWORD', 'FIREBASE_PROJECT_ID', 'FILES_DIR']
+        },
+        conventions: {
+            protectRoutes: 'Every route under /api/v1 calls call.requireUser() before it reads the body or looks anything up (401 without a valid token). ' +
+                'With sharing, a route on a space\'s data calls call.requireRole(spaces, spaceId, Role.VIEWER) to read and Role.EDITOR to write, ' +
+                'then uses the returned membership.spaceId.',
+            notFoundRule: 'A row the caller may not see (another user\'s, or with sharing a space where the caller is not a member or has too low a role) ' +
+                'answers 404 NOT_FOUND exactly like a missing row: never 403. Every query filters by the owner (owner_id, or space_id with sharing) in the same query.',
+            newFeature: 'Put a new feature under src/main/kotlin/<package>/feature/<name>/ copying feature/sample (table, repository, routes, DTOs), ' +
+                'add a new migration V<n>__<name>.sql (never edit one that has run), its tests (IDOR and validation included) and its routes in openapi/OpenApiSpec.kt.',
+            newTable: 'Every new table points at its owner with REFERENCES users(id) ON DELETE CASCADE (with sharing: spaces(id) ON DELETE CASCADE), ' +
+                'so account deletion removes its rows.',
+            securityChecklist: 'Go through SECURITY-CHECKLIST.md for every new route or table: authorization, owner filter, validation at the boundary, ' +
+                'DTOs without id/owner/role fields, no SQL string building, no personal data in logs, rate limits on sensitive routes.',
+            errors: 'Fail with notFound(), badRequest(...) or an ApiException; the body is {"error":{"code","message","requestId"}} (+ fields for validation). ' +
+                'A 500 carries no detail.',
+            runLocal: `./gradlew ${S.anatomy.localTask} serves on 127.0.0.1:${port} with an embedded PostgreSQL in .local-server/; ` +
+                'it needs .local-server/config.properties with firebaseProjectId=<Firebase project id> (optional port=). ' +
+                './gradlew resetLocal deletes .local-server/; ./gradlew build compiles, runs detekt and the tests.',
+            deploy: `${S.anatomy.deployDir}/ holds the Dockerfile (container port 8080), docker-compose.<appName>.yml, nginx/<appName>.conf, ` +
+                'sql/create-<appName>.sql, .env.example and README.md (first deployment, updates, rollback); secrets come only from the environment. ' +
+                'bash tools/deploy-lint.sh checks them.',
+            clientHeaders: 'The app sends Authorization: Bearer <Firebase ID token> and X-Client-Version; below MIN_CLIENT_VERSION the answer is 426 CLIENT_UPGRADE_REQUIRED.'
+        }
+    };
+}
+
+module.exports = { describeBackend };

package/src/backend/generate.js

@@ -0,0 +1,39 @@
+'use strict';
+const path = require('path');
+const fs = require('fs-extra');
+const { log } = require('../log');
+const { COMMIT_FILE_NAME, REF_FILE_NAME } = require('../templateVersions');
+const { applySharingOption } = require('./options');
+const { applyBackendIdentity } = require('./identity');
+const { writeBackendRecord } = require('./record');
+const { verifyBackendProject } = require('./verifier');
+
+// The template cache's own records and the template's gate and notes never reach the project (tools/deploy-lint.sh stays)
+const LEFTOVERS = ['.git', COMMIT_FILE_NAME, REF_FILE_NAME, path.join('tools', 'gate.sh'), path.join('tools', 'TEMPLATE.md')];
+
+// Turns a fresh backend template copy (projectDir) into the requested project, in place. value: validateBackend().value.
+// templateRef and templateCommit default to the cache's markers. Throws when a step fails or the result fails verification.
+async function generateBackend(value, { projectDir, templateRef = null, templateCommit = null, generatorVersion = null, now = new Date() }) {
+    const readMarker = (name) => fs.readFile(path.join(projectDir, name), 'utf8').then((v) => v.trim() || null, () => null);
+    const ref = templateRef || (await readMarker(REF_FILE_NAME));
+    const commit = templateCommit || (await readMarker(COMMIT_FILE_NAME));
+
+    // 1. options, before the package moves (tools/sharing-paths.txt names the template's package dir)
+    await applySharingOption(projectDir, value.sharing);
+    log.info(`✅ Sharing ${value.sharing ? 'on' : 'off'}`);
+
+    // 2. identity
+    await applyBackendIdentity(projectDir, value);
+    log.info(`✅ Renamed to ${value.appName} (${value.packageName})`);
+
+    // 3. leftovers, then the record
+    for (const leftover of LEFTOVERS) await fs.remove(path.join(projectDir, leftover));
+    const record = await writeBackendRecord(projectDir, value, { templateRef: ref, templateCommit: commit, generatorVersion, now });
+
+    // 4. a broken project is never returned
+    const problems = await verifyBackendProject(projectDir, value);
+    if (problems.length) throw new Error(`backend verification failed: ${problems.join('; ')}`);
+    return { sharing: value.sharing, record };
+}
+
+module.exports = { generateBackend };

package/src/backend/identity.js

@@ -0,0 +1,109 @@
+'use strict';
+const path = require('path');
+const fs = require('fs-extra');
+const { BACKEND_SCHEMA: S } = require('./contract');
+const { PRUNED } = require('./options');
+
+const TEMPLATE_APP = S.identity.appName;
+const dbName = (appName) => appName.replace(/-/g, '_');
+const envPrefix = (appName) => dbName(appName).toUpperCase();
+
+/** The template's identity tokens and what each becomes */
+function identityPairs({ packageName, appName, projectName }) {
+    return [
+        { from: S.identity.package, to: packageName },
+        { from: S.identity.package.replace(/\./g, '/'), to: packageName.replace(/\./g, '/') },
+        { from: S.identity.projectName, to: projectName },
+        { from: TEMPLATE_APP, to: appName },
+        { from: dbName(TEMPLATE_APP), to: dbName(appName) },
+        { from: envPrefix(TEMPLATE_APP), to: envPrefix(appName) }
+    ];
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+// One pass, so a new name is never renamed again
+function renameAll(pairs) {
+    const to = new Map(pairs.map((p) => [p.from, p.to]));
+    const re = new RegExp([...to.keys()].sort((a, b) => b.length - a.length).map(escapeRe).join('|'), 'g');
+    return (text) => text.replace(re, (m) => to.get(m));
+}
+// A file with a NUL byte is binary (gradle-wrapper.jar) and keeps its bytes
+const isBinary = (buffer) => buffer.includes(0);
+
+async function walk(dir, rel, out) {
+    for (const entry of await fs.readdir(path.join(dir, rel), { withFileTypes: true })) {
+        if (PRUNED.has(entry.name)) continue;
+        const r = rel ? path.join(rel, entry.name) : entry.name;
+        if (entry.isDirectory()) {
+            out.push({ rel: r, dir: true });
+            await walk(dir, r, out);
+        } else if (entry.isFile()) {
+            out.push({ rel: r, dir: false });
+        }
+    }
+    return out;
+}
+
+// Moves every file of the template package dir (any source set) into the new package dir, then drops the emptied dirs
+async function movePackageDirs(projectDir, packageName) {
+    const from = S.identity.package.split('.');
+    const to = packageName.split('.');
+    const srcDir = path.join(projectDir, 'src');
+    if (!(await fs.pathExists(srcDir))) return;
+    for (const sourceSet of await fs.readdir(srcDir)) {
+        const kotlinDir = path.join(srcDir, sourceSet, 'kotlin');
+        const oldDir = path.join(kotlinDir, ...from);
+        if (!(await fs.pathExists(oldDir))) continue;
+        const newDir = path.join(kotlinDir, ...to);
+        const staging = path.join(kotlinDir, `.cmpose-package-${process.pid}`);
+        await fs.move(oldDir, staging);
+        // the template package's parents (io/cmpose) go when nothing else lives in them
+        for (let depth = from.length - 1; depth > 0; depth--) {
+            const parent = path.join(kotlinDir, ...from.slice(0, depth));
+            if ((await fs.readdir(parent)).length) break;
+            await fs.remove(parent);
+        }
+        if (await fs.pathExists(newDir)) throw new Error(`cannot move the package to ${path.relative(projectDir, newDir)}: it exists`);
+        await fs.move(staging, newDir);
+    }
+}
+
+/** Renames the template's package, app name (and its database and env forms) and display name: in the text files, the
+ * package dirs and every file or dir name holding the app name. Binary files and file modes stay. */
+async function applyBackendIdentity(projectDir, { packageName, appName, projectName }) {
+    const rename = renameAll(identityPairs({ packageName, appName, projectName }));
+    const entries = await walk(projectDir, '', []);
+
+    // 1. content
+    for (const e of entries) {
+        if (e.dir) continue;
+        const file = path.join(projectDir, e.rel);
+        const buffer = await fs.readFile(file);
+        if (isBinary(buffer)) continue;
+        const text = buffer.toString('utf8');
+        const next = rename(text);
+        if (next !== text) await fs.writeFile(file, next);
+    }
+
+    // 2. package dirs
+    await movePackageDirs(projectDir, packageName);
+
+    // 3. names holding the app name, deepest first; every target is checked before anything moves
+    const appRename = renameAll([{ from: TEMPLATE_APP, to: appName }]);
+    const moves = (await walk(projectDir, '', []))
+        .filter((e) => path.basename(e.rel).includes(TEMPLATE_APP))
+        .sort((a, b) => b.rel.split(path.sep).length - a.rel.split(path.sep).length)
+        .map((e) => {
+            const from = path.join(projectDir, e.rel);
+            return { rel: e.rel, from, to: path.join(path.dirname(from), appRename(path.basename(from))) };
+        });
+    const targets = new Set();
+    for (const m of moves) {
+        if (targets.has(m.to) || (await fs.pathExists(m.to))) throw new Error(`cannot rename ${m.rel}: target exists`);
+        targets.add(m.to);
+    }
+    for (const m of moves) await fs.move(m.from, m.to);
+    return { renamedFiles: moves.length };
+}
+
+module.exports = { applyBackendIdentity, identityPairs, dbName, envPrefix };

package/src/backend/index.js

@@ -0,0 +1,24 @@
+'use strict';
+const { validateBackend } = require('./validate');
+const { BACKEND_SCHEMA, backendContractVersion } = require('./contract');
+const { applySharingOption, resolveContent } = require('./options');
+const { applyBackendIdentity } = require('./identity');
+const { verifyBackendProject } = require('./verifier');
+const { RECORD_PATH, buildBackendRecord, writeBackendRecord } = require('./record');
+const { generateBackend } = require('./generate');
+const { describeBackend } = require('./describe');
+
+module.exports = {
+    validateBackend,
+    BACKEND_SCHEMA,
+    backendContractVersion,
+    applySharingOption,
+    resolveContent,
+    applyBackendIdentity,
+    verifyBackendProject,
+    RECORD_PATH,
+    buildBackendRecord,
+    writeBackendRecord,
+    generateBackend,
+    describeBackend
+};

package/src/backend/options.js

@@ -0,0 +1,159 @@
+'use strict';
+const path = require('path');
+const fs = require('fs-extra');
+const { kindOf } = require('../markerBlocks');
+
+// The backend template's sharing part, resolved exactly as the template's tools/resolve-markers.sh does (the gate's
+// reference), so a generated project is byte for byte what the template's gate built and tested:
+//   on:  only the marker lines go; a swap marker goes and the line after it stays.
+//   off: each marked block goes with its markers, a swap marker's text replaces the line after it (at that line's
+//        indentation), the paths of tools/sharing-paths.txt go, and so do the Kotlin imports the rest no longer names.
+// Either way a blank line on both sides of a dropped run becomes one. Files are read as latin1, so bytes round-trip.
+
+const TAG = 'sharing';
+const PATHS_FILE = path.join('tools', 'sharing-paths.txt');
+// The resolver's own tools, which a generated project has no use for
+const RESOLVER_TOOLS = ['sharing-paths.txt', 'resolve-markers.sh', 'resolve-markers.test.sh'];
+// The directories the resolver never enters, at any depth
+const PRUNED = new Set(['.git', 'build', '.gradle', '.kotlin', '.local-server', 'node_modules']);
+const COMMENTS = { slash: '//', dash: '--', hash: '#' };
+const IMPORT_RE = /^import[ \t]+[A-Za-z0-9_.`]+([ \t]+as[ \t]+[A-Za-z0-9_`]+)?[ \t]*$/;
+const WORD = /[A-Za-z0-9_]/;
+
+// awk's trim: spaces and tabs at the start; spaces, tabs and \r at the end
+const trim = (s) => s.replace(/^[ \t]+/, '').replace(/[ \t\r]+$/, '');
+
+function formsOf(kind) {
+    if (kind === 'xml') return { open: `<!-- cmpose:${TAG} -->`, close: `<!-- /cmpose:${TAG} -->`, swap: '', prefix: '<!--' };
+    const c = COMMENTS[kind];
+    return { open: `${c} cmpose:${TAG}`, close: `${c} /cmpose:${TAG}`, swap: `${c} cmpose:${TAG}-off: `, prefix: c };
+}
+
+// A line that looks like a marker but is none of the known forms
+function malformed(t, prefix) {
+    if (!t.startsWith(prefix)) return false;
+    return t.slice(prefix.length).replace(/^[ \t]*\/?/, '').startsWith('cmpose:');
+}
+
+// Whether the code names <name> as a whole word
+function names(code, name) {
+    for (let at = code.indexOf(name); at >= 0; at = code.indexOf(name, at + 1)) {
+        const before = at > 0 ? code[at - 1] : '';
+        const after = code[at + name.length] || '';
+        if (!WORD.test(before) && !WORD.test(after)) return true;
+    }
+    return false;
+}
+
+// The Kotlin imports (star imports aside) whose simple name or alias the rest of the file no longer names
+function dropUnusedImports(lines) {
+    const code = lines.filter((l) => !IMPORT_RE.test(l)).map((l) => `${l}\n`).join('');
+    return lines.filter((line) => {
+        if (!IMPORT_RE.test(line) || /\.\*[ \t]*$/.test(line)) return true;
+        let name = trim(line);
+        name = /[ \t]as[ \t]/.test(name) ? name.replace(/^.*[ \t]as[ \t]+/, '') : name.replace(/^.*\./, '');
+        return names(code, name.replace(/`/g, ''));
+    });
+}
+
+/** One file's content resolved (enabled = on); throws `<file>:<line>: <problem>` on a marker error */
+function resolveContent(content, kind, enabled, { file = 'file', kotlin = false } = {}) {
+    const { open, close, swap, prefix } = formsOf(kind);
+    const lines = content.split('\n');
+    if (content.endsWith('\n')) lines.pop();
+    const die = (message, at) => { throw new Error(`${file}:${at}: ${message}`); };
+    const out = [];
+    let inside = false;
+    let opened = 0;
+    let dropped = false;
+    let joining = false;
+    const emit = (s) => {
+        if (dropped) { joining = true; dropped = false; }
+        if (joining) {
+            if (s === '' && out.length && out[out.length - 1] === '') return;
+            joining = false;
+        }
+        out.push(s);
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const t = trim(line);
+        if (t === open) {
+            if (inside) die(`nested cmpose:${TAG} block (open since line ${opened})`, i + 1);
+            inside = true; opened = i + 1; dropped = true;
+            continue;
+        }
+        if (t === close) {
+            if (!inside) die('block close without an open', i + 1);
+            inside = false; dropped = true;
+            continue;
+        }
+        if (inside && !enabled) continue;
+        if (swap && t.startsWith(swap)) {
+            if (i === lines.length - 1) die(`cmpose:${TAG}-off marker on the last line`, i + 1);
+            let next = lines[i + 1];
+            const nt = trim(next);
+            if (nt === open || nt === close || malformed(nt, prefix)) die(`cmpose:${TAG}-off marker before a marker`, i + 1);
+            if (!enabled) next = next.match(/^[ \t]*/)[0] + t.slice(swap.length);
+            i++;
+            emit(next);
+            continue;
+        }
+        if (malformed(t, prefix)) die(`malformed cmpose marker: ${t}`, i + 1);
+        emit(line);
+    }
+    if (inside) die(`unclosed cmpose:${TAG} block`, opened);
+    const kept = kotlin && !enabled ? dropUnusedImports(out) : out;
+    return kept.map((l) => `${l}\n`).join('');
+}
+
+// Every file below dir outside the pruned directories, as paths relative to dir
+async function listFiles(dir, rel = '', out = []) {
+    for (const entry of await fs.readdir(path.join(dir, rel), { withFileTypes: true })) {
+        if (PRUNED.has(entry.name)) continue;
+        const r = rel ? path.join(rel, entry.name) : entry.name;
+        if (entry.isDirectory()) await listFiles(dir, r, out);
+        else if (entry.isFile()) out.push(r);
+    }
+    return out;
+}
+
+// The sharing-only paths: relative, inside the project
+async function readSharingPaths(projectDir) {
+    const file = path.join(projectDir, PATHS_FILE);
+    if (!(await fs.pathExists(file))) throw new Error(`${PATHS_FILE} is missing`);
+    const paths = [];
+    for (const raw of (await fs.readFile(file, 'utf8')).split('\n')) {
+        const p = raw.replace(/\r$/, '');
+        if (p === '' || p.startsWith('#')) continue;
+        const slashed = `/${p}/`;
+        if (slashed.startsWith('//') || slashed.includes('/../') || slashed.includes('/./')) {
+            throw new Error(`${PATHS_FILE}: '${p}' must be a relative path inside the project`);
+        }
+        paths.push(p);
+    }
+    return paths;
+}
+
+/** Resolves the sharing markers of a fresh template copy in place, then drops the resolver's own tools. Every file is
+ * resolved before any is written, so a marker error leaves the directory as it was. */
+async function applySharingOption(projectDir, enabled) {
+    const results = [];
+    for (const rel of await listFiles(projectDir)) {
+        const kind = kindOf(rel);
+        if (!kind) continue;
+        const file = path.join(projectDir, rel);
+        const content = await fs.readFile(file, 'latin1');
+        if (!content.includes('cmpose:')) continue;
+        const kotlin = rel.endsWith('.kt') || rel.endsWith('.kts');
+        results.push({ file, content: resolveContent(content, kind, enabled, { file: rel, kotlin }) });
+    }
+    const sharingPaths = enabled ? [] : await readSharingPaths(projectDir);
+    // writeFile keeps an existing file's mode
+    for (const { file, content } of results) await fs.writeFile(file, content, 'latin1');
+    for (const p of sharingPaths) await fs.remove(path.join(projectDir, p));
+    for (const tool of RESOLVER_TOOLS) await fs.remove(path.join(projectDir, 'tools', tool));
+    return { resolvedFiles: results.length, removedPaths: sharingPaths };
+}
+
+module.exports = { applySharingOption, resolveContent, PRUNED };

package/src/backend/record.js

@@ -0,0 +1,31 @@
+'use strict';
+const path = require('path');
+const fs = require('fs-extra');
+const pins = require('../pins');
+const { backendContractVersion } = require('./contract');
+
+const RECORD_PATH = path.join('.cmpose', 'generation.json');
+
+/** The .cmpose/generation.json content of a generated backend: the options and the template, no personal data
+ * (no output dir); generatorVersion names the caller (e.g. mcp@0.4.0), null when not given */
+function buildBackendRecord(value, { templateRef = null, templateCommit = null, generatorVersion = null, now = new Date() } = {}) {
+    return {
+        generator: '@cmpose/core',
+        coreVersion: require('../../package.json').version,
+        generatorVersion: generatorVersion || null,
+        kind: 'backend',
+        contractVersion: backendContractVersion(),
+        sharing: value.sharing === true,
+        template: { repo: pins.backend.repo, ref: templateRef || null, commit: templateCommit || null },
+        generatedAt: now.toISOString()
+    };
+}
+
+async function writeBackendRecord(projectDir, value, options = {}) {
+    const record = buildBackendRecord(value, options);
+    const file = path.join(projectDir, RECORD_PATH);
+    await fs.outputFile(file, `${JSON.stringify(record, null, 2)}\n`);
+    return record;
+}
+
+module.exports = { RECORD_PATH, buildBackendRecord, writeBackendRecord };

package/src/backend/validate.js

@@ -0,0 +1,64 @@
+'use strict';
+const path = require('path');
+const PV = require('../ProjectValidator');
+const { BACKEND_SCHEMA: S } = require('./contract');
+
+const APP_NAME_RE = new RegExp(S.appName.pattern);
+// templateCache's ref rule: a tag or branch name, never a path
+const REF_RE = /^[A-Za-z0-9_.-]+$/;
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const isTemplatePackage = (v) => v === S.identity.package || v.startsWith(S.identity.package + '.');
+
+// Why an appName cannot name a server service, a database and its user (null = it can)
+function databaseNameProblem(appName) {
+    const dbName = appName.replace(/-/g, '_');
+    if (S.appName.infrastructure.includes(appName)) {
+        return `appName "${appName}" is a server service name (${S.appName.infrastructure.join(', ')})`;
+    }
+    if (S.appName.postgresReserved.includes(dbName)) return `appName "${appName}" is a PostgreSQL reserved name (${S.appName.postgresReserved.join(', ')})`;
+    if (dbName.startsWith(S.appName.postgresPrefix)) return `appName "${appName}" starts with pg-: PostgreSQL reserves ${S.appName.postgresPrefix} for its own roles`;
+    if (S.appName.sqlKeywords.includes(dbName)) return `appName "${appName}" gives the database name ${dbName}, a PostgreSQL reserved key word`;
+    return null;
+}
+
+// Every problem as { field, message }; the value holds only the known fields (sharing defaults to false)
+function validateBackend(input) {
+    if (!isObject(input)) return { ok: false, errors: [{ field: 'input', message: 'input must be an object' }] };
+    const { projectName, appName, packageName, outputDir, sharing, templateRef } = input;
+    const errors = [];
+    const fail = (field, message) => errors.push({ field, message });
+
+    if (typeof projectName !== 'string' || !PV.validateProjectName(projectName)) fail('projectName', PV.messages.projectNameInvalid);
+    else if (projectName.length > PV.MAX_LENGTH_PROJECT_NAME) fail('projectName', PV.messages.projectNameTooLong);
+
+    if (typeof appName !== 'string' || !APP_NAME_RE.test(appName)) {
+        fail('appName', 'appName must be 2-31 lowercase letters, digits or -, starting with a letter');
+    } else if (S.appName.reserved.includes(appName)) {
+        fail('appName', `appName "${appName}" is reserved (${S.appName.reserved.join(', ')})`);
+    } else {
+        const problem = databaseNameProblem(appName);
+        if (problem) fail('appName', problem);
+    }
+
+    if (typeof packageName !== 'string' || !PV.validatePackageName(packageName) || isTemplatePackage(packageName)) {
+        fail('packageName', PV.messages.packageNameInvalid);
+    } else if (packageName.length > PV.MAX_LENGTH_PACKAGE_NAME) {
+        fail('packageName', PV.messages.packageNameTooLong);
+    }
+
+    if (typeof outputDir !== 'string' || !path.isAbsolute(outputDir)) fail('outputDir', 'outputDir must be an absolute path');
+
+    if (sharing !== undefined && typeof sharing !== 'boolean') fail('sharing', 'sharing must be true or false');
+
+    if (templateRef !== undefined && (typeof templateRef !== 'string' || !REF_RE.test(templateRef) || templateRef.startsWith('.'))) {
+        fail('templateRef', 'templateRef must be a tag or branch name (letters, digits, ., _ or -, not starting with .)');
+    }
+
+    if (errors.length) return { ok: false, errors };
+    const value = { projectName, appName, packageName, outputDir, sharing: sharing === undefined ? S.options.sharing.default : sharing };
+    if (templateRef !== undefined) value.templateRef = templateRef;
+    return { ok: true, value };
+}
+
+module.exports = { validateBackend };

package/src/backend/verifier.js

@@ -0,0 +1,69 @@
+'use strict';
+const path = require('path');
+const fs = require('fs-extra');
+const { PRUNED } = require('./options');
+const { identityPairs } = require('./identity');
+
+// A marker line of any form (// -- # <!--), open, close, swap or malformed
+const MARKER_RE = /^[ \t]*(?:\/\/|--|#|<!--)[ \t]*\/?cmpose:/m;
+// The template gate's sharing words, in the code, docs and deploy parts
+const SHARING_WORDS = /space|invite|member/i;
+const SHARING_TARGETS = ['src', 'SECURITY-CHECKLIST.md', 'deploy', 'README.md'];
+const SECRET_PATTERNS = [
+    { name: 'private key', re: /-----BEGIN .*PRIVATE KEY-----/ },
+    { name: 'service account key', re: /"private_key":/ },
+    { name: 'Google API key', re: /AIza[0-9A-Za-z_-]{35}/ }
+];
+// tools/ scripts may spell the marker forms
+const MARKER_SKIPPED = 'tools';
+// The one template tool a project keeps
+const KEPT_TOOLS = ['tools/deploy-lint.sh'];
+
+async function listFiles(dir, rel = '', out = []) {
+    for (const entry of await fs.readdir(path.join(dir, rel), { withFileTypes: true })) {
+        if (PRUNED.has(entry.name)) continue;
+        const r = rel ? `${rel}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) { await listFiles(dir, r, out); continue; }
+        if (!entry.isFile()) continue;
+        const buffer = await fs.readFile(path.join(dir, r));
+        // a binary file (gradle-wrapper.jar) is checked by name only
+        out.push({ rel: r, text: buffer.includes(0) ? '' : buffer.toString('utf8') });
+    }
+    return out;
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** Problems of a generated backend project (empty = clean), sorted */
+async function verifyBackendProject(projectDir, { sharing, packageName, appName, projectName = '' }) {
+    const problems = [];
+    const pairs = identityPairs({ packageName, appName, projectName });
+    // A template token the project's own names spell (a package io.cmpose.backendtemplatex) is not residue
+    const tokens = pairs.filter((p) => !p.to.includes(p.from)).map((p) => p.from);
+    // The project's own names never count as sharing words (an app named space-notes)
+    const ownNames = pairs.map((p) => p.to).filter(Boolean).sort((a, b) => b.length - a.length);
+    const ownNamesRe = ownNames.length ? new RegExp(ownNames.map(escapeRe).join('|'), 'g') : null;
+
+    for (const { rel, text } of await listFiles(projectDir)) {
+        for (const token of tokens) {
+            if (rel.includes(token)) problems.push(`old identity ${token} in the name ${rel}`);
+            if (text.includes(token)) problems.push(`old identity ${token} in ${rel}`);
+        }
+        if (rel.split('/')[0] !== MARKER_SKIPPED && MARKER_RE.test(text)) problems.push(`marker left in ${rel}`);
+        if (rel.startsWith('tools/') && !KEPT_TOOLS.includes(rel)) problems.push(`template tool left in ${rel}`);
+        if (!sharing && SHARING_TARGETS.some((t) => rel === t || rel.startsWith(`${t}/`))) {
+            const own = ownNamesRe ? text.replace(ownNamesRe, '') : text;
+            if (SHARING_WORDS.test(own)) problems.push(`sharing word in ${rel} (sharing is off)`);
+        }
+        for (const { name, re } of SECRET_PATTERNS) if (re.test(text)) problems.push(`${name} in ${rel}`);
+    }
+
+    const packageDir = path.posix.join('src', 'main', 'kotlin', ...packageName.split('.'));
+    if (!(await fs.pathExists(path.join(projectDir, packageDir)))) problems.push(`missing package dir ${packageDir}`);
+    for (const rel of [`deploy/docker-compose.${appName}.yml`, `deploy/nginx/${appName}.conf`]) {
+        if (!(await fs.pathExists(path.join(projectDir, rel)))) problems.push(`missing ${rel}`);
+    }
+    return problems.sort();
+}
+
+module.exports = { verifyBackendProject };