@cmpose/core 0.5.3 → 0.6.0

package/package.json

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

package/src/backend/contract.js

@@ -26,7 +26,10 @@ const BACKEND_SCHEMA = Object.freeze({
             'user', 'using', 'variadic', 'verbose', 'when', 'where', 'window', 'with'
         ])
     }),
-    options: Object.freeze({ sharing: Object.freeze({ type: 'boolean', default: false }) }),
+    options: Object.freeze({
+        sharing: Object.freeze({ type: 'boolean', default: false }),
+        sample: Object.freeze({ type: 'boolean', default: true })
+    }),
     // 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' })

package/src/backend/describe.js

@@ -14,6 +14,11 @@ function describeBackend() {
                 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.'
+            },
+            sample: {
+                type: S.options.sample.type,
+                default: S.options.sample.default,
+                description: 'Include the sample items feature (feature/sample) as the shape to copy'
             }
         },
         appNameRules: {
@@ -31,9 +36,9 @@ function describeBackend() {
                 '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>/users': 'GET and DELETE /api/v1/me, PUT /api/v1/me/profile',
                 '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>/feature/sample': 'the sample feature (/api/v1/items): the shape to copy (sample only)',
                 '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)',
@@ -51,7 +56,8 @@ function describeBackend() {
                 '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), ' +
+            newFeature: 'Put a new feature under src/main/kotlin/<package>/feature/<name>/ (table, repository, routes, DTOs) ' +
+                'copying feature/sample when present, otherwise the shape of files/; ' +
                 '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.',

package/src/backend/generate.js

@@ -3,12 +3,15 @@ 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 { applySharingOption, applySampleOption, removeResolverTools } = 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)
+// Added with the sample option: a template without it is older than this generator (an error, never tolerated)
+const SAMPLE_PATHS_FILE = path.join('tools', 'sample-paths.txt');
+
 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.
@@ -18,9 +21,19 @@ async function generateBackend(value, { projectDir, templateRef = null, template
     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)
+    // 0. a template older than the sample option cannot be generated: say which one, before anything changes
+    if (!(await fs.pathExists(path.join(projectDir, SAMPLE_PATHS_FILE)))) {
+        throw new Error(`backend template ${ref || '(unknown ref)'} predates the sample option `
+            + '(no tools/sample-paths.txt); use a newer backend template tag');
+    }
+
+    // 1. options, sharing then sample (the template gate's order), before the package moves (tools/<option>-paths.txt
+    // names the template's package dir); then the resolver's own tools go
     await applySharingOption(projectDir, value.sharing);
     log.info(`✅ Sharing ${value.sharing ? 'on' : 'off'}`);
+    await applySampleOption(projectDir, value.sample);
+    log.info(`✅ Sample ${value.sample ? 'on' : 'off'}`);
+    await removeResolverTools(projectDir);
 
     // 2. identity
     await applyBackendIdentity(projectDir, value);
@@ -33,7 +46,7 @@ async function generateBackend(value, { projectDir, templateRef = null, template
     // 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 };
+    return { sharing: value.sharing, sample: value.sample, record };
 }
 
 module.exports = { generateBackend };

package/src/backend/index.js

@@ -1,7 +1,7 @@
 'use strict';
-const { validateBackend } = require('./validate');
+const { validateBackend, templateRefProblem } = require('./validate');
 const { BACKEND_SCHEMA, backendContractVersion } = require('./contract');
-const { applySharingOption, resolveContent } = require('./options');
+const { applyMarkerOption, applySharingOption, applySampleOption, removeResolverTools, resolveContent } = require('./options');
 const { applyBackendIdentity } = require('./identity');
 const { verifyBackendProject } = require('./verifier');
 const { RECORD_PATH, buildBackendRecord, writeBackendRecord } = require('./record');
@@ -10,9 +10,13 @@ const { describeBackend } = require('./describe');
 
 module.exports = {
     validateBackend,
+    templateRefProblem,
     BACKEND_SCHEMA,
     backendContractVersion,
+    applyMarkerOption,
     applySharingOption,
+    applySampleOption,
+    removeResolverTools,
     resolveContent,
     applyBackendIdentity,
     verifyBackendProject,

package/src/backend/options.js

@@ -3,38 +3,51 @@ 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:
+// The backend template's optional parts (cmpose:<option>: sharing, sample), resolved exactly as the template's
+// tools/resolve-markers.sh <dir> <option> on|off 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.
+//        indentation), the paths of tools/<option>-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.
+// A run sees only its own option's markers (another option's marker lines are plain text, so blocks of different
+// options may nest), except that the line after a swap may not be a marker of any option. The generator runs
+// sharing first, then sample.
 
-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'];
+const OPTION_RE = /^[a-z]+$/;
+const pathsFileOf = (tag) => path.join('tools', `${tag}-paths.txt`);
+// The resolver's own tools (with every tools/*-paths.txt), which a generated project has no use for
+const RESOLVER_TOOLS = ['resolve-markers.sh', 'resolve-markers.test.sh'];
+const PATHS_FILE_RE = /-paths\.txt$/;
 // 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: '#' };
+// Every marker comment style, for what a swap must not stand before
+const ANY_STYLE = ['//', '--', '#', '<!--'];
 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: '<!--' };
+function formsOf(kind, tag) {
+    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 };
+    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) {
+// A line that looks like a marker of this option (cmpose:<tag> not followed by a letter) but is none of the known forms
+function malformed(t, prefix, tag) {
     if (!t.startsWith(prefix)) return false;
-    return t.slice(prefix.length).replace(/^[ \t]*\/?/, '').startsWith('cmpose:');
+    const rest = t.slice(prefix.length).replace(/^[ \t]*\/?/, '');
+    const marker = `cmpose:${tag}`;
+    return rest.startsWith(marker) && !/[a-z]/.test(rest.charAt(marker.length));
 }
 
+// A line that looks like a marker of any option, in any comment style
+const anyMarker = (t) => ANY_STYLE.some((style) => t.startsWith(style)
+    && t.slice(style.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)) {
@@ -56,9 +69,10 @@ function dropUnusedImports(lines) {
     });
 }
 
-/** 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);
+/** One file's content with the markers of one option (tag) resolved (enabled = on); throws `<file>:<line>: <problem>`
+ * on a marker error */
+function resolveContent(content, kind, enabled, { file = 'file', kotlin = false, tag = 'sharing' } = {}) {
+    const { open, close, swap, prefix } = formsOf(kind, tag);
     const lines = content.split('\n');
     if (content.endsWith('\n')) lines.pop();
     const die = (message, at) => { throw new Error(`${file}:${at}: ${message}`); };
@@ -79,7 +93,7 @@ function resolveContent(content, kind, enabled, { file = 'file', kotlin = false
         const line = lines[i];
         const t = trim(line);
         if (t === open) {
-            if (inside) die(`nested cmpose:${TAG} block (open since line ${opened})`, i + 1);
+            if (inside) die(`nested cmpose:${tag} block (open since line ${opened})`, i + 1);
             inside = true; opened = i + 1; dropped = true;
             continue;
         }
@@ -90,19 +104,21 @@ function resolveContent(content, kind, enabled, { file = 'file', kotlin = false
         }
         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);
+            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 (nt === open || nt === close || malformed(nt, prefix, tag) || anyMarker(nt)) {
+                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);
+        if (malformed(t, prefix, tag)) die(`malformed cmpose marker: ${t}`, i + 1);
         emit(line);
     }
-    if (inside) die(`unclosed cmpose:${TAG} block`, opened);
+    if (inside) die(`unclosed cmpose:${tag} block`, opened);
     const kept = kotlin && !enabled ? dropUnusedImports(out) : out;
     return kept.map((l) => `${l}\n`).join('');
 }
@@ -118,42 +134,55 @@ async function listFiles(dir, rel = '', out = []) {
     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`);
+// The option-only paths: relative, inside the project
+async function readOptionPaths(projectDir, pathsFile) {
     const paths = [];
-    for (const raw of (await fs.readFile(file, 'utf8')).split('\n')) {
+    for (const raw of (await fs.readFile(path.join(projectDir, pathsFile), '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`);
+            throw new Error(`${pathsFile}: '${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) {
+/** Resolves the cmpose:<tag> markers of a template copy in place and, when off, deletes the paths of
+ * tools/<tag>-paths.txt. Only the files holding a marker of this option are resolved. The paths file must exist in
+ * either mode, and every file is resolved before any is written, so an error leaves the directory as it was. */
+async function applyMarkerOption(projectDir, tag, enabled) {
+    if (typeof tag !== 'string' || !OPTION_RE.test(tag)) throw new Error(`option must be lowercase letters: ${JSON.stringify(tag)}`);
+    const pathsFile = pathsFileOf(tag);
+    if (!(await fs.pathExists(path.join(projectDir, pathsFile)))) throw new Error(`${pathsFile.split(path.sep).join('/')} is missing`);
+    // the resolver's file pick: cmpose:<tag> not followed by a letter
+    const own = new RegExp(`cmpose:${tag}([^a-z]|$)`, 'm');
     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;
+        if (!own.test(content)) continue;
         const kotlin = rel.endsWith('.kt') || rel.endsWith('.kts');
-        results.push({ file, content: resolveContent(content, kind, enabled, { file: rel, kotlin }) });
+        results.push({ file, content: resolveContent(content, kind, enabled, { file: rel, kotlin, tag }) });
     }
-    const sharingPaths = enabled ? [] : await readSharingPaths(projectDir);
+    const optionPaths = enabled ? [] : await readOptionPaths(projectDir, pathsFile);
     // 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 };
+    for (const p of optionPaths) await fs.remove(path.join(projectDir, p));
+    return { resolvedFiles: results.length, removedPaths: optionPaths };
+}
+
+const applySharingOption = (projectDir, enabled) => applyMarkerOption(projectDir, 'sharing', enabled);
+const applySampleOption = (projectDir, enabled) => applyMarkerOption(projectDir, 'sample', enabled);
+
+/** Deletes the resolver's own tools: tools/resolve-markers.sh, tools/resolve-markers.test.sh and every tools/*-paths.txt */
+async function removeResolverTools(projectDir) {
+    const tools = path.join(projectDir, 'tools');
+    const names = (await fs.pathExists(tools)) ? await fs.readdir(tools) : [];
+    for (const name of [...RESOLVER_TOOLS, ...names.filter((n) => PATHS_FILE_RE.test(n))]) await fs.remove(path.join(tools, name));
 }
 
-module.exports = { applySharingOption, resolveContent, PRUNED };
+module.exports = { applyMarkerOption, applySharingOption, applySampleOption, removeResolverTools, resolveContent, PRUNED };

package/src/backend/record.js

@@ -16,6 +16,7 @@ function buildBackendRecord(value, { templateRef = null, templateCommit = null,
         kind: 'backend',
         contractVersion: backendContractVersion(),
         sharing: value.sharing === true,
+        sample: value.sample !== false,
         template: { repo: pins.backend.repo, ref: templateRef || null, commit: templateCommit || null },
         generatedAt: now.toISOString()
     };

package/src/backend/validate.js

@@ -22,24 +22,35 @@ function databaseNameProblem(appName) {
     return null;
 }
 
-// Every problem as { field, message }; the value holds only the known fields (sharing defaults to false)
+// Why appName cannot name a backend (null = it can): the pattern, the route prefixes, then the database name
+function appNameProblem(appName) {
+    if (typeof appName !== 'string' || !APP_NAME_RE.test(appName)) {
+        return 'appName must be 2-31 lowercase letters, digits or -, starting with a letter';
+    }
+    if (S.appName.reserved.includes(appName)) return `appName "${appName}" is reserved (${S.appName.reserved.join(', ')})`;
+    return databaseNameProblem(appName);
+}
+
+// Why ref cannot name a backend template tag (null = it can); field names the input in the message
+function templateRefProblem(ref, field = 'templateRef') {
+    if (typeof ref !== 'string' || !REF_RE.test(ref) || ref.startsWith('.')) {
+        return `${field} must be a tag or branch name (letters, digits, ., _ or -, not starting with .)`;
+    }
+    return null;
+}
+
+// Every problem as { field, message }; the value holds only the known fields (sharing defaults to false, sample to true)
 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 { projectName, appName, packageName, outputDir, sharing, sample, 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);
-    }
+    const nameProblem = appNameProblem(appName);
+    if (nameProblem) fail('appName', nameProblem);
 
     if (typeof packageName !== 'string' || !PV.validatePackageName(packageName) || isTemplatePackage(packageName)) {
         fail('packageName', PV.messages.packageNameInvalid);
@@ -50,15 +61,21 @@ function validateBackend(input) {
     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 (sample !== undefined && typeof sample !== 'boolean') fail('sample', 'sample 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 (templateRef !== undefined) {
+        const problem = templateRefProblem(templateRef);
+        if (problem) fail('templateRef', problem);
     }
 
     if (errors.length) return { ok: false, errors };
-    const value = { projectName, appName, packageName, outputDir, sharing: sharing === undefined ? S.options.sharing.default : sharing };
+    const value = {
+        projectName, appName, packageName, outputDir,
+        sharing: sharing === undefined ? S.options.sharing.default : sharing,
+        sample: sample === undefined ? S.options.sample.default : sample
+    };
     if (templateRef !== undefined) value.templateRef = templateRef;
     return { ok: true, value };
 }
 
-module.exports = { validateBackend };
+module.exports = { validateBackend, templateRefProblem, appNameProblem };

package/src/backend/verifier.js

@@ -8,6 +8,9 @@ const { identityPairs } = require('./identity');
 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;
+// The template gate's sample words (no_sample_words), in the same parts
+const SAMPLE_WORDS = /feature[./]sample|\/items|Item(Repository|Routes|Table|Dto|OpenApi)|V3__sample/;
+const SAMPLE_MIGRATION = 'V3__sample.sql';
 const SHARING_TARGETS = ['src', 'SECURITY-CHECKLIST.md', 'deploy', 'README.md'];
 const SECRET_PATTERNS = [
     { name: 'private key', re: /-----BEGIN .*PRIVATE KEY-----/ },
@@ -35,7 +38,7 @@ async function listFiles(dir, rel = '', out = []) {
 const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
 /** Problems of a generated backend project (empty = clean), sorted */
-async function verifyBackendProject(projectDir, { sharing, packageName, appName, projectName = '' }) {
+async function verifyBackendProject(projectDir, { sharing, sample, 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
@@ -51,15 +54,19 @@ async function verifyBackendProject(projectDir, { sharing, packageName, appName,
         }
         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}/`))) {
+        if (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)`);
+            if (!sharing && SHARING_WORDS.test(own)) problems.push(`sharing word in ${rel} (sharing is off)`);
+            if (sample === false && SAMPLE_WORDS.test(own)) problems.push(`sample word in ${rel} (sample is off)`);
         }
+        if (sample === false && path.posix.basename(rel) === SAMPLE_MIGRATION) problems.push(`sample migration ${rel} left (sample 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}`);
+    const sampleDir = path.posix.join(packageDir, 'feature', 'sample');
+    if (sample === false && (await fs.pathExists(path.join(projectDir, sampleDir)))) problems.push(`sample dir ${sampleDir} left (sample is off)`);
     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}`);
     }

package/src/backendOption.js

@@ -10,7 +10,7 @@ const { removeMarkedBlocks, applySwapMarkers } = require('./markerBlocks');
 
 const KIND_BY_EXTENSION = {
     '.kt': 'slash', '.kts': 'slash', '.swift': 'slash', '.xcconfig': 'slash',
-    '.toml': 'hash', '.gitignore': 'hash', '.properties': 'hash',
+    '.toml': 'hash', '.gitignore': 'hash', '.properties': 'hash', '.yml': 'hash', '.yaml': 'hash',
     '.md': 'html', '.xml': 'html', '.plist': 'html', '.xcprivacy': 'html'
 };
 const SKIP_DIRS = new Set(['.git', '.gradle', 'build', 'node_modules']);
@@ -18,6 +18,7 @@ const SKIP_DIRS = new Set(['.git', '.gradle', 'build', 'node_modules']);
 // Template-relative paths the backend adds outside the files it marks; deleted when backend is off
 const TEMPLATE_PACKAGE_PATH = 'com/kturker/multiplatform';
 const BACKEND_PATHS = [
+    // The template has no server/ of its own (it comes from the backend template); kept so a stale fetched copy goes too
     'server',
     'core/api',
     'core/auth',

package/src/contract.js

@@ -31,7 +31,7 @@ const SCHEMA = {
             'core/purchases': { requires: ['purchases'], note: 'offer / purchase / restore API, RevenueCat KMP (Test Store key: replace before you ship)' },
             'core/ads': { requires: ['ads'], note: 'AdMob banner/interstitial/rewarded + UMP/ATT consent (test IDs)' },
             'core/room': { requires: ['room'], note: 'Room KMP database (bundled SQLite): AppDatabase, DAOs, schemas/' },
-            'core/api': { requires: ['backend'], note: 'models and routes shared by the app and the server' },
+            'core/api': { requires: ['backend'], note: "the app's client models and routes for the backend API, checked by ApiContractTest" },
             'core/auth': { requires: ['backend'], note: 'Firebase sign-in (email, Google, Apple); the server client\'s token' }
         },
         // featuresConfig flag -> feature modules kept in a blank project (same requires/requiresAny rules).

package/src/featureModules.js

@@ -34,6 +34,10 @@ const BLANK_ONLY_FEATURES = ['notes'];
 const NOTES_INCLUDE_REGEX = /^\s*include\("?:?feature:notes(?::(?:contract|presentation))?"\)\s*$/;
 // Cloned modules carry no test sources (Compass counts the iOS tests of a project as the agent's)
 const TEST_SOURCE_SET_REGEX = /(^|\/)src\/[^/]*Test\//;
+// The template test source sets a blank project keeps: Android-host checks only, never an iOS test. shared's Koin
+// graph check, and core/api's contract test (ApiContractTest: the app's models and routes against server/; core/api
+// is there only with the backend)
+const BLANK_KEPT_TEST_DIRS = ['shared/src/androidHostTest/', 'core/api/src/androidHostTest/'];
 
 function capitalize(name) {
     return name.charAt(0).toUpperCase() + name.slice(1);
@@ -159,8 +163,8 @@ const MONETIZATION_CAPABILITIES = [
     { dir: `${BLANK_OVERLAY_DIR}/${LAYERS_DIR}/${MONETIZATION_LAYER.name}`, needed: MONETIZATION_LAYER.applies }
 ];
 // Checked per request only: a readiness check (no config) does not need them, so a template pinned
-// before the backend release still serves every other option
-const BACKEND_CAPABILITIES = ['server', 'core/api', 'core/auth', 'feature/account', 'feature/sharing']
+// before the backend release still serves every other option (server/ comes from the backend template)
+const BACKEND_CAPABILITIES = ['core/api', 'core/auth', 'feature/account', 'feature/sharing']
     .map((dir) => ({ dir, needed: (cfg) => cfg.backend === true }));
 
 class TemplateCapabilityError extends Error {
@@ -242,6 +246,6 @@ async function cloneFeatureModules(projectPath, features) {
 }
 
 module.exports = {
-    applyBlankShell, cloneFeatureModules, wrapLongSingleParamSignatures, capitalize, TEST_SOURCE_SET_REGEX,
+    applyBlankShell, cloneFeatureModules, wrapLongSingleParamSignatures, capitalize, TEST_SOURCE_SET_REGEX, BLANK_KEPT_TEST_DIRS,
     assertTemplateCapabilities, missingTemplateCapabilities, templateLacksMessage, TemplateCapabilityError
 };

package/src/fileService.js

@@ -3,7 +3,7 @@ const path = require('path');
 const { listTextFiles } = require('./projectFiles');
 const { removeSwiftPackage } = require('./xcodePackages');
 const { stripPins } = require('./backendOption');
-const { capitalize, TEST_SOURCE_SET_REGEX } = require('./featureModules');
+const { capitalize, TEST_SOURCE_SET_REGEX, BLANK_KEPT_TEST_DIRS } = require('./featureModules');
 const { removeMarkedBlock } = require('./readmeService');
 const { log } = require('./log');
 
@@ -84,12 +84,13 @@ const TEMPLATE_FEATURE_MODULES = {
     sharing: (cfg) => cfg.backend === true
 };
 
-// Deletes every test source set (src/*Test) of a Gradle module; a missing src/ is fine
-async function removeTestSourceSets(moduleDir) {
+// Deletes every test source set (src/*Test) of a Gradle module but those in BLANK_KEPT_TEST_DIRS; a missing src/ is fine
+async function removeTestSourceSets(projectPath, moduleDir) {
     const srcDir = path.join(moduleDir, 'src');
     if (!(await fs.pathExists(srcDir))) return;
     for (const sourceSet of await fs.readdir(srcDir)) {
-        if (TEST_SOURCE_SET_REGEX.test(`src/${sourceSet}/`)) await fs.remove(path.join(srcDir, sourceSet));
+        const rel = `${path.relative(projectPath, srcDir).split(path.sep).join('/')}/${sourceSet}/`;
+        if (TEST_SOURCE_SET_REGEX.test(rel) && !BLANK_KEPT_TEST_DIRS.includes(rel)) await fs.remove(path.join(srcDir, sourceSet));
     }
 }
 
@@ -926,8 +927,9 @@ async function processBlankApp(projectPath, packageName, features, featuresConfi
 
     // The template's own core tests (ThemeModeTest, ColorSchemeForTest, ...) stay in the showcase.
     // Compass counts every iOS test of a project as the agent's, so a blank app starts with none
-    // (clones carry none either, see featureModules.js); shared's Android-host Koin graph check stays.
-    // The same goes for the layers of the template's own feature modules (monetization, notes).
+    // (clones carry none either, see featureModules.js). The Android-host checks of BLANK_KEPT_TEST_DIRS stay:
+    // shared's Koin graph check and, with the backend, core/api's contract test against server/.
+    // The same goes for the layers of the template's own feature modules (monetization, notes, account, sharing).
     const testParents = [
         path.join(projectPath, 'core'),
         ...Object.keys(TEMPLATE_FEATURE_MODULES).map((module) => path.join(projectPath, 'feature', module))
@@ -935,7 +937,7 @@ async function processBlankApp(projectPath, packageName, features, featuresConfi
     for (const parentDir of testParents) {
         if (!(await fs.pathExists(parentDir))) continue;
         for (const moduleName of await fs.readdir(parentDir)) {
-            await removeTestSourceSets(path.join(parentDir, moduleName));
+            await removeTestSourceSets(projectPath, path.join(parentDir, moduleName));
         }
     }
 
@@ -1706,6 +1708,8 @@ async function processCoreFeatures(projectPath, config, packageName) {
                     'ktor-client-core',
                     'ktor-client-darwin',
                     'ktor-client-logging',
+                    // core/network's test client (MockEngine)
+                    'ktor-client-mock',
                     'ktor-serialization-kotlinx-json',
                     // Coil's network fetcher lives in core:network and goes with it
                     'coil-network-ktor3'
@@ -2188,19 +2192,10 @@ async function processCoreFeatures(projectPath, config, packageName) {
             }
         }
 
-        // 6. Modules outside the convention plugins that apply it by id (core/api and the server: the
-        // backend's JVM-capable modules)
+        // 6. Modules outside the convention plugins that apply it by id (core/api, the backend's JVM-capable module;
+        // server/ is the backend template's own build with its own detekt, placed after this step)
         const detektPluginLine = `id("${packageName}.detekt")`;
-        for (const moduleDir of [path.join(projectPath, 'core', 'api'), path.join(projectPath, 'server')]) {
-            await dropLines(path.join(moduleDir, 'build.gradle.kts'), (line) => line.trim() === detektPluginLine);
-        }
-        // The server also points detekt at its local runner's sources
-        const serverGradle = path.join(projectPath, 'server', 'build.gradle.kts');
-        if (await fs.pathExists(serverGradle)) {
-            const content = await fs.readFile(serverGradle, 'utf8');
-            const cleaned = content.replace(/(?:^|\n)(?:\/\/[^\n]*\n)?detekt \{ source\.from\("src\/local\/kotlin"\) \}\n(?:[ \t]*\n)?/, '\n');
-            if (cleaned !== content) await fs.writeFile(serverGradle, cleaned);
-        }
+        await dropLines(path.join(projectPath, 'core', 'api', 'build.gradle.kts'), (line) => line.trim() === detektPluginLine);
 
         // The CI workflow's detekt step would fail without the plugin
         const ciPath = path.join(projectPath, '.github', 'workflows', 'ci.yml');

package/src/generate.js

@@ -16,12 +16,24 @@ const { fillReadme } = require('./readmeService');
 const { buildGenerationRecord, writeGenerationRecord } = require('./generationRecord');
 const { verifyGeneratedProject } = require('./generationVerifier');
 const { generationWarnings } = require('./warnings');
+const { placeServer, SERVER_DIR } = require('./serverFromBackend');
 
 // Turns a fresh template copy (projectDir) into the requested project, in place.
 // value: validate().value. Throws when the template lacks an option or the result fails verification.
-async function generateCmpProject(value, { projectDir, generatorVersion = null }) {
+// backendTemplate ({ dir, repo, ref, commit }): a fresh backend template copy, required for blank with the backend; it
+// is moved into the project as server/. serverImageCheck: the verifier's server image check (opt-in: a check, true for
+// Docker, false for none; unset, CMPOSE_SERVER_IMAGE_CHECK=1 asks for Docker).
+async function generateCmpProject(value, { projectDir, generatorVersion = null, backendTemplate = null, serverImageCheck } = {}) {
     const { projectName, appName, packageName, templateType, features, featuresConfig, ci, minSdk, iosVersion } = value;
     const blankConfig = templateType === 'blank' ? featuresConfig : null;
+    const backendOn = templateType === 'blank' && featuresConfig.backend === true;
+    // Before anything is touched: server/ comes from the backend template only
+    if (backendOn && !(backendTemplate && backendTemplate.dir)) {
+        throw new Error('backend: the backend template is required (backendTemplate)');
+    }
+    if (backendOn && (await fs.pathExists(path.join(projectDir, SERVER_DIR)))) {
+        throw new Error(`backend: the CMP template already has ${SERVER_DIR}/, which comes from the backend template (use a newer templateRef)`);
+    }
 
     // An older template without the modules an on flag needs stops here, naming what is missing
     await assertTemplateCapabilities(projectDir, templateType, featuresConfig);
@@ -54,7 +66,7 @@ async function generateCmpProject(value, { projectDir, generatorVersion = null }
     // template's own package before the rename below
     await applyBlankShell(projectDir, templateType, featuresConfig);
     // The backend's parts stay (markers dropped) for blank with backend on; everywhere else they go
-    await applyBackendOption(projectDir, templateType === 'blank' && featuresConfig.backend === true);
+    await applyBackendOption(projectDir, backendOn);
     await cloneFeatureModules(projectDir, sanitizedFeatures);
     log.info(`✅ Template skeleton ready (${sanitizedFeatures.length} feature modules)`);
 
@@ -82,21 +94,29 @@ async function generateCmpProject(value, { projectDir, generatorVersion = null }
     // Store-ready: the privacy manifest declares the data the on flags collect (showcase: ads and
     // purchases on, never backend)
     await writePrivacyManifest(projectDir, templateType === 'blank'
-        ? { ads: featuresConfig.ads === true, purchases: featuresConfig.purchases === true, backend: featuresConfig.backend === true }
+        ? { ads: featuresConfig.ads === true, purchases: featuresConfig.purchases === true, backend: backendOn }
         : { ads: true, purchases: true, backend: false });
     log.info('✅ iOS configuration updated');
 
-    await fillReadme(projectDir, { versions, minSdk, iosVersion });
-
     // Package rename and module cloning moved imports out of ktlint order: re-sort them last
     await sortKotlinImports(projectDir);
 
+    // server/ comes from the backend template, after the app's rename and import sort (which never touch it)
+    const server = backendOn
+        ? await placeServer(projectDir, { packageName, projectName, backendTemplate, generatorVersion })
+        : null;
+    const serverTemplate = server ? server.template : null;
+
+    // After server/ is in place: the module list names it
+    await fillReadme(projectDir, { versions, minSdk, iosVersion });
+
     // The project's trace: which template, which generator, which options; no personal data
     await writeGenerationRecord(projectDir, buildGenerationRecord({
         templateRef, templateCommit, backendRevision: generatorVersion,
         templateType, ci, minSdk, iosVersion,
         features: sanitizedFeatures,
-        featuresConfig: blankConfig
+        featuresConfig: blankConfig,
+        serverTemplate
     }));
 
     // Last check: a broken project is never returned
@@ -104,12 +124,13 @@ async function generateCmpProject(value, { projectDir, generatorVersion = null }
         projectName, appName, packageName, templateType,
         features: sanitizedFeatures,
         featuresConfig: blankConfig
-    });
+    }, { serverImageCheck });
 
     return {
         projectDir, templateRef, templateCommit, templateType,
         features: sanitizedFeatures,
         versions,
+        serverTemplate,
         warnings: generationWarnings({ templateType, featuresConfig })
     };
 }

package/src/generationRecord.js

@@ -32,13 +32,20 @@ function sanitizeFeaturesConfig(featuresConfig) {
     return { ...rest, customDetektYaml: typeof detektYamlContent === 'string' && detektYamlContent.trim().length > 0 };
 }
 
-/** The .cmpose/generation.json content written into the generated project (no personal data) */
-function buildGenerationRecord({ templateRef, templateCommit, backendRevision, templateType, ci, minSdk, iosVersion, features, featuresConfig, now = new Date() }) {
+/** The .cmpose/generation.json content written into the generated project (no personal data). backendRevision names
+ * the generator (backend.revision); serverTemplate is the backend template server/ came from, null without one. */
+function buildGenerationRecord({
+    templateRef, templateCommit, backendRevision, templateType, ci, minSdk, iosVersion, features, featuresConfig,
+    serverTemplate = null, now = new Date()
+}) {
     return {
         generator: 'cmpose',
         generatedAt: now.toISOString(),
         template: { ref: templateRef || null, commit: templateCommit || null },
         backend: { revision: backendRevision || null },
+        serverTemplate: serverTemplate
+            ? { repo: serverTemplate.repo || null, ref: serverTemplate.ref || null, commit: serverTemplate.commit || null }
+            : null,
         options: {
             templateType,
             ci: ci === true,

package/src/generationVerifier.js

@@ -1,9 +1,12 @@
 const fs = require('fs-extra');
 const path = require('path');
+const { execFile } = require('child_process');
+const { log } = require('./log');
 const { listTextFiles } = require('./projectFiles');
 const { escapeRegExp, findResidue, BACKEND_RESIDUE_TOKENS } = require('./fileService');
-const { TEST_SOURCE_SET_REGEX } = require('./featureModules');
+const { TEST_SOURCE_SET_REGEX, BLANK_KEPT_TEST_DIRS } = require('./featureModules');
 const { OLD_PACKAGE_NAME } = require('./templateIdentity');
+const { SERVER_DIR, INCLUDE_SERVER_BUILD, serverPackageOf } = require('./serverFromBackend');
 
 // The template's own identity: if it is left in a generated project, the rename missed a spot.
 // The user's input can carry the same text (appName accepts dots and letters, ≤30; the project name
@@ -81,8 +84,6 @@ function capitalize(name) {
 }
 
 const relPath = (projectPath, file) => path.relative(projectPath, file).split(path.sep).join('/');
-// The one test source set blank keeps: the Android-host Koin graph check
-const KOIN_GRAPH_TEST_DIR = 'shared/src/androidHostTest/';
 
 // Blank's shell wires the theme and the strings through its layers; Theming off leaves
 // no reference to the theme packages it removes; no template test ships (Compass's test gate).
@@ -118,7 +119,7 @@ async function verifyBlankShell(projectPath, input, problems) {
     for (const file of files) {
         const filePath = relPath(projectPath, file);
         const match = filePath.match(TEST_SOURCE_SET_REGEX);
-        if (!match || filePath.startsWith(KOIN_GRAPH_TEST_DIR)) continue;
+        if (!match || BLANK_KEPT_TEST_DIRS.some((dir) => filePath.startsWith(dir))) continue;
         const dir = filePath.slice(0, match.index + match[0].length - 1);
         problems.add(`${dir}: template tests in a blank project (Compass counts every iOS test as the agent's)`);
     }
@@ -498,8 +499,8 @@ async function readIfExists(file) {
 // Backend: blank keeps the server, core/api, core/auth, feature/account and feature/sharing exactly when its
 // backend flag is on, wired, with the Google Sign-In URL scheme left to the build setting; otherwise (and
 // always in showcase) none of them and no reference to them. No cmpose:backend marker is ever left.
+// server/ is the backend template, an included build (includeBuild("server")), so it is checked apart from the modules.
 const BACKEND_MODULES = [
-    { dir: 'server', build: 'server/build.gradle.kts', include: ':server' },
     { dir: 'core/api', build: 'core/api/build.gradle.kts', include: ':core:api' },
     { dir: 'core/auth', build: 'core/auth/build.gradle.kts', include: ':core:auth' },
     { dir: 'feature/account', build: 'feature/account/presentation/build.gradle.kts', include: ':feature:account:presentation' },
@@ -509,6 +510,44 @@ const BACKEND_SHARED_DEPENDENCIES = ['projects.core.auth', 'projects.feature.acc
 const BACKEND_KOIN_MODULES = ['AuthModule', 'AccountModule', 'SharingModule'];
 const GOOGLE_URL_SCHEME = '<string>$(GOOGLE_REVERSED_CLIENT_ID)</string>';
 const BACKEND_MARKER = 'cmpose:backend';
+const LOCAL_SERVER_DIR = /^[ \t]*localServerDir[ \t]*=[ \t]*\.\.\/\.local-server[ \t]*$/m;
+const BACKEND_TEMPLATE_PACKAGE = 'io.cmpose.backendtemplate';
+const SERVER_PRUNED = new Set(['.git', '.gradle', '.kotlin', 'build', '.local-server']);
+
+// Every file under server/ (build output aside) holding the backend template's own package: the rename missed it
+async function serverTemplateResidue(projectPath, rel = SERVER_DIR, out = []) {
+    for (const entry of await fs.readdir(path.join(projectPath, rel), { withFileTypes: true })) {
+        if (SERVER_PRUNED.has(entry.name)) continue;
+        const child = `${rel}/${entry.name}`;
+        if (child.includes(BACKEND_TEMPLATE_PACKAGE.replace(/\./g, '/'))) out.push(child);
+        if (entry.isDirectory()) {
+            await serverTemplateResidue(projectPath, child, out);
+        } else if (entry.isFile()) {
+            const buffer = await fs.readFile(path.join(projectPath, child));
+            if (!buffer.includes(0) && buffer.toString('utf8').includes(BACKEND_TEMPLATE_PACKAGE)) out.push(child);
+        }
+    }
+    return out;
+}
+
+async function verifyServer(projectPath, input, settings, problems) {
+    const exists = (rel) => fs.pathExists(path.join(projectPath, rel));
+    for (const rel of ['server/settings.gradle.kts', 'server/build.gradle.kts']) {
+        if (!(await exists(rel))) problems.add(`${rel}: missing although backend is on`);
+    }
+    if (!INCLUDE_SERVER_BUILD.test(settings)) problems.add('settings.gradle.kts: includeBuild("server") missing although backend is on');
+    if (!LOCAL_SERVER_DIR.test(await readIfExists(path.join(projectPath, SERVER_DIR, 'gradle.properties')))) {
+        problems.add('server/gradle.properties: localServerDir=../.local-server missing (the local server lives in the root .local-server/)');
+    }
+    if (await exists('server/.github')) problems.add('server/.github: the backend template\'s CI left (the project\'s own CI builds server/)');
+    const serverPath = serverPackageOf(input.packageName).replace(/\./g, '/');
+    for (const rel of [`server/src/main/kotlin/${serverPath}`, `server/src/local/kotlin/${serverPath}/local/LocalMain.kt`]) {
+        if (!(await exists(rel))) problems.add(`${rel}: missing although backend is on`);
+    }
+    // A package that spells the template's own (io.cmpose.backendtemplate.x) is the user's, not residue
+    if (!(await exists(SERVER_DIR)) || input.packageName.includes(BACKEND_TEMPLATE_PACKAGE)) return;
+    for (const rel of new Set(await serverTemplateResidue(projectPath))) problems.add(`${rel}: ${BACKEND_TEMPLATE_PACKAGE} left`);
+}
 
 async function verifyBackend(projectPath, input, cfg, problems) {
     const on = input.templateType === 'blank' && cfg.backend === true;
@@ -520,7 +559,7 @@ async function verifyBackend(projectPath, input, cfg, problems) {
 
     if (!on) {
         const where = input.templateType === 'blank' ? 'although backend is off' : 'in a showcase project';
-        for (const { dir } of BACKEND_MODULES) {
+        for (const dir of [SERVER_DIR, ...BACKEND_MODULES.map((m) => m.dir)]) {
             if (await exists(dir)) problems.add(`${dir}: present ${where}`);
         }
         const tokens = BACKEND_RESIDUE_TOKENS.filter((token) => token.label !== BACKEND_MARKER);
@@ -535,6 +574,7 @@ async function verifyBackend(projectPath, input, cfg, problems) {
         if (!(await exists(build))) problems.add(`${build}: missing although backend is on`);
         if (!settings.includes(`"${include}"`)) problems.add(`settings.gradle.kts: ${include} not included`);
     }
+    await verifyServer(projectPath, input, settings, problems);
     const sharedBuild = await readIfExists(path.join(projectPath, 'shared', 'build.gradle.kts'));
     for (const dependency of BACKEND_SHARED_DEPENDENCIES) {
         if (!new RegExp(`\\b${escapeRegExp(dependency)}(?![A-Za-z0-9.])`).test(sharedBuild)) {
@@ -554,12 +594,77 @@ async function verifyBackend(projectPath, input, cfg, problems) {
     }
 }
 
+// One version for both platforms (the server's X-Client-Version check compares it): the iOS MARKETING_VERSION equals
+// AppConfig.versionName. Keyed on both values, so a template without them (staging, an older tag) is not checked.
+async function verifyAppVersion(projectPath, problems) {
+    const xcconfig = await readIfExists(path.join(projectPath, 'iosApp/Configuration/Config.xcconfig'));
+    const marketing = xcconfig.match(/^[ \t]*MARKETING_VERSION[ \t]*=[ \t]*([^\s]+)[ \t]*$/m);
+    const appConfig = await readIfExists(path.join(projectPath, 'build-logic/src/main/kotlin/config/AppConfig.kt'));
+    const part = (name) => (appConfig.match(new RegExp(`\\b${name}\\s*=\\s*(\\d+)\\b`)) || [])[1];
+    const [major, minor, patch] = ['versionMajor', 'versionMinor', 'versionPatch'].map(part);
+    if (!marketing || major === undefined || minor === undefined || patch === undefined) return;
+    const versionName = `${major}.${minor}.${patch}`;
+    if (marketing[1] !== versionName) problems.add(`iOS MARKETING_VERSION (${marketing[1]}) must equal AppConfig.versionName (${versionName})`);
+}
+
+const run = (command, args, options) => new Promise((resolve) => {
+    execFile(command, args, { maxBuffer: 64 * 1024 * 1024, ...options }, (error, stdout, stderr) => resolve({ error, stdout, stderr }));
+});
+const DOCKER_INFO_TIMEOUT_MS = 20000;
+const DOCKER_BUILD_TIMEOUT_MS = 30 * 60 * 1000;
+
+/** The server image check: docker build -f server/deploy/Dockerfile server. { status: 'PASS' | 'SKIP' | 'FAIL', detail };
+ * SKIP when Docker (the docker command and its daemon) is not available */
+async function checkServerImage(projectPath, { docker = 'docker' } = {}) {
+    const info = await run(docker, ['info', '--format', '{{.ServerVersion}}'], { timeout: DOCKER_INFO_TIMEOUT_MS });
+    if (info.error) return { status: 'SKIP', detail: 'Docker is not available' };
+    const build = await run(docker, ['build', '--quiet', '-f', path.join(SERVER_DIR, 'deploy', 'Dockerfile'), SERVER_DIR],
+        { cwd: projectPath, timeout: DOCKER_BUILD_TIMEOUT_MS });
+    if (build.error) {
+        const tail = `${build.stderr || build.error.message}`.trim().split('\n').slice(-5).join(' | ');
+        return { status: 'FAIL', detail: tail };
+    }
+    // The image itself is not kept (the build cache is)
+    const image = build.stdout.trim().split('\n').pop();
+    if (image) await run(docker, ['image', 'rm', image], { timeout: DOCKER_INFO_TIMEOUT_MS });
+    return { status: 'PASS', detail: image };
+}
+
+const SERVER_IMAGE_ENV = 'CMPOSE_SERVER_IMAGE_CHECK';
+const NOT_REQUESTED = `not requested (set ${SERVER_IMAGE_ENV}=1)`;
+
+/** Which server image check runs, null = none. Opt-in: the option (a check function, true for the Docker check, false
+ * for none) wins; without it, CMPOSE_SERVER_IMAGE_CHECK=1 asks for the Docker check. Generation for an end user never
+ * pays minutes for an image or loses a valid project to the network. */
+function resolveServerImageCheck(option, env = process.env) {
+    if (typeof option === 'function') return option;
+    if (option === true) return checkServerImage;
+    if (option === false) return null;
+    return env[SERVER_IMAGE_ENV] === '1' ? checkServerImage : null;
+}
+
+// The server image builds (the backend template's own gate does not build it with the app's server package); skipped
+// without Docker, and unless asked for
+async function verifyServerImage(projectPath, serverImageCheck, problems) {
+    const { status, detail } = serverImageCheck
+        ? await serverImageCheck(projectPath)
+        : { status: 'SKIP', detail: NOT_REQUESTED };
+    if (status === 'FAIL') {
+        problems.add(`server/deploy/Dockerfile: the server image does not build (docker build -f server/deploy/Dockerfile server): ${detail}`);
+    } else {
+        log.info(`${status === 'PASS' ? '✅' : '⏭️'} server image: ${status}${status === 'SKIP' && detail ? ` (${detail})` : ''}`);
+    }
+}
+
 /**
  * Checks the generated project right before it is zipped; throws if anything is wrong (the request fails).
  * @param {string} projectPath
  * @param {{ projectName: string, appName: string, packageName: string, templateType: string, features: string[], featuresConfig?: object | null }} input
+ * @param {{ serverImageCheck?: boolean | ((projectPath: string) => Promise<{ status: 'PASS' | 'SKIP' | 'FAIL', detail?: string }>),
+ *   env?: object }} [options] the server image check (backend on; resolveServerImageCheck: opt-in, the option or
+ *   CMPOSE_SERVER_IMAGE_CHECK=1 in env), run last and only when nothing else failed
  */
-async function verifyGeneratedProject(projectPath, input) {
+async function verifyGeneratedProject(projectPath, input, { serverImageCheck, env = process.env } = {}) {
     const packagePath = input.packageName.replace(/\./g, '/');
     const problems = new Set();
 
@@ -666,6 +771,13 @@ async function verifyGeneratedProject(projectPath, input) {
     // 14. Backend: the server and its modules exactly when blank's backend flag is on, no residue otherwise
     await verifyBackend(projectPath, input, input.featuresConfig || {}, problems);
 
+    // 15. One app version for both platforms
+    await verifyAppVersion(projectPath, problems);
+
+    // 16. The server image, last: it takes minutes, so only a project that passed everything else is built
+    const backendOn = input.templateType === 'blank' && (input.featuresConfig || {}).backend === true;
+    if (backendOn && problems.size === 0) await verifyServerImage(projectPath, resolveServerImageCheck(serverImageCheck, env), problems);
+
     if (problems.size > 0) {
         // Cap the message: a badly broken generation (many unwired modules) can produce dozens of
         // lines, which is unreadable in an error response or a log line.
@@ -678,4 +790,4 @@ async function verifyGeneratedProject(projectPath, input) {
     }
 }
 
-module.exports = { verifyGeneratedProject, verifyBackend };
+module.exports = { verifyGeneratedProject, verifyBackend, verifyAppVersion, checkServerImage, resolveServerImageCheck, SERVER_IMAGE_ENV };

package/src/index.js

@@ -34,6 +34,9 @@ module.exports = {
     minSdkAboveTarget: require('./validate').minSdkAboveTarget,
     generationWarnings: require('./warnings').generationWarnings,
     generateCmpProject: require('./generate').generateCmpProject,
+    // server/ from the backend template (also the template maintainers' fetch-server script)
+    placeServer: require('./serverFromBackend').placeServer,
+    deriveServerAppName: require('./serverFromBackend').deriveServerAppName,
     templateCache: require('./templateCache'),
     game: require('./game'),
     backend: require('./backend'),

package/src/pins.js

@@ -1,9 +1,9 @@
 'use strict';
 // The template tags this core version was tested with (immutable tags)
 module.exports = Object.freeze({
-    cmp: Object.freeze({ repo: 'whinstudio/cmpose-template', ref: 'template-2026.10.17' }),
+    cmp: Object.freeze({ repo: 'whinstudio/cmpose-template', ref: 'template-2026.10.20' }),
     // The release step replaces the placeholder with the game template's tag
     game: Object.freeze({ repo: 'whinstudio/cmpose-game-template', ref: 'game-template-2026.10.19' }),
     // The release step replaces the placeholder with the backend template's tag
-    backend: Object.freeze({ repo: 'whinstudio/cmpose-backend-template', ref: 'backend-template-2026.10.19' })
+    backend: Object.freeze({ repo: 'whinstudio/cmpose-backend-template', ref: 'backend-template-2026.10.20' })
 });

package/src/readmeService.js

@@ -1,6 +1,7 @@
 const { log } = require('./log');
 const fs = require('fs-extra');
 const path = require('path');
+const { INCLUDE_SERVER_BUILD, SERVER_DIR } = require('./serverFromBackend');
 
 // The generated README's requirements table and module map. The template's README marks
 // both sections (<!-- cmpose:requirements --> … <!-- /cmpose:requirements -->); a README without
@@ -24,7 +25,7 @@ const CORE_DESCRIPTIONS = {
     update: 'app updates: Play In-App Updates, the App Store lookup and an optional minimum version',
     ads: 'AdMob ads and consent (test IDs)',
     room: 'Room database (bundled SQLite): AppDatabase, DAOs and schemas',
-    api: 'models and routes shared by the app and the server',
+    api: "the app's client models and routes for the backend API, checked by ApiContractTest",
     auth: "Firebase sign-in: email, Google, Apple; the server client's token"
 };
 
@@ -48,7 +49,12 @@ function renderRequirements(versions, { minSdk, iosVersion }) {
     ].join('\n');
 }
 
-function renderModules(settingsContent) {
+// server/ is an included build (INCLUDE_SERVER_BUILD), not a module
+const SERVER_LINE = '- `server/`: Ktor server from the cmpose backend template (an included build): sign-in check, spaces, sharing, files; '
+    + '`./gradlew :server:runLocal`; deploying: `server/deploy/README.md`';
+
+// serverDir: whether the project has server/ (the settings include it only when it is there)
+function renderModules(settingsContent, { serverDir = false } = {}) {
     const paths = [...settingsContent.matchAll(/^\s*include\(([^)]*)\)/gm)]
         .flatMap((m) => [...m[1].matchAll(/"(:?[^"]+)"/g)].map((q) => q[1]))
         .map((p) => (p.startsWith(':') ? p : `:${p}`));
@@ -66,9 +72,7 @@ function renderModules(settingsContent) {
         const layers = paths.filter((x) => x.startsWith(`:feature:${feature}:`)).map((x) => x.split(':')[3]).sort();
         lines.push(layers.length ? `- \`:feature:${feature}\`: ${layers.join(', ')}` : `- \`:feature:${feature}\``);
     }
-    if (paths.includes(':server')) {
-        lines.push('- `:server`: Ktor server: sign-in check, spaces, sharing, files; `./gradlew :server:runLocal`');
-    }
+    if (serverDir && INCLUDE_SERVER_BUILD.test(settingsContent)) lines.push(SERVER_LINE);
     return lines.join('\n');
 }
 
@@ -99,7 +103,8 @@ async function fillReadme(projectPath, { versions, minSdk, iosVersion }) {
         if (!content.includes('<!-- cmpose:requirements -->') && !content.includes('<!-- cmpose:modules -->')) return false;
         const settings = await fs.readFile(path.join(projectPath, 'settings.gradle.kts'), 'utf8').catch(() => '');
         let updated = replaceBetweenMarkers(content, 'cmpose:requirements', renderRequirements(versions, { minSdk, iosVersion }));
-        updated = replaceBetweenMarkers(updated, 'cmpose:modules', renderModules(settings));
+        const serverDir = await fs.pathExists(path.join(projectPath, SERVER_DIR));
+        updated = replaceBetweenMarkers(updated, 'cmpose:modules', renderModules(settings, { serverDir }));
         await fs.writeFile(readmePath, updated);
         return true;
     } catch (error) {

package/src/serverFromBackend.js

@@ -0,0 +1,82 @@
+'use strict';
+const path = require('path');
+const fs = require('fs-extra');
+const { log } = require('./log');
+const { appNameProblem } = require('./backend/validate');
+const { generateBackend } = require('./backend/generate');
+
+// A blank project's server/ is the cmpose backend template, generated in place as an included build (the root settings
+// include it with includeBuild("server")): sharing on, sample off, the package <app package>.server, and the local
+// server's folder at the project root (.local-server/, Compass's contract).
+
+const SERVER_DIR = 'server';
+const LOCAL_SERVER_DIR_LINE = 'localServerDir=../.local-server';
+// The root settings' includeBuild("server") on a line that is not a comment (the template guards it with an if)
+const INCLUDE_SERVER_BUILD = /^(?![ \t]*\/\/).*\bincludeBuild\("server"\)/m;
+// The template's CI and the backend's own generation record: the app's CI and record cover server/
+const SERVER_LEFTOVERS = ['.github', '.cmpose'];
+const BASE_MAX = 27;
+
+const serverPackageOf = (packageName) => `${packageName}.server`;
+
+// The project name in kebab case (MyApp -> my-app, MyAPIApp -> my-api-app), cut at BASE_MAX without a trailing -
+function kebabBase(projectName) {
+    const kebab = String(projectName)
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^[^a-z]+/, '');
+    return kebab.slice(0, BASE_MAX).replace(/-+$/, '');
+}
+
+/** The server's appName for a project: the project name in kebab case, then with -app, then with -server; the first
+ * one the backend's appName rule accepts */
+function deriveServerAppName(projectName) {
+    const base = kebabBase(projectName);
+    for (const candidate of [base, `${base}-app`, `${base}-server`]) {
+        if (!appNameProblem(candidate)) return candidate;
+    }
+    throw new Error(`Cannot derive a server name from ${projectName}`);
+}
+
+// localServerDir=../.local-server as the file's own line (an existing localServerDir line is replaced)
+async function writeLocalServerDir(serverDir) {
+    const file = path.join(serverDir, 'gradle.properties');
+    const content = (await fs.pathExists(file)) ? await fs.readFile(file, 'utf8') : '';
+    const lines = content.split('\n').filter((line) => !/^\s*localServerDir\s*=/.test(line));
+    while (lines.length && lines[lines.length - 1] === '') lines.pop();
+    lines.push(LOCAL_SERVER_DIR_LINE);
+    await fs.writeFile(file, `${lines.join('\n')}\n`);
+}
+
+/** Moves a fresh backend template copy (backendTemplate.dir) to <projectDir>/server and generates it there. Fails when
+ * server/ already exists. Returns the server's appName, package and template.
+ * On a failure part way, server/ may be half written: the caller discards the project dir. */
+async function placeServer(projectDir, { packageName, projectName, backendTemplate, generatorVersion = null, now = new Date() }) {
+    const { dir, repo = null, ref = null, commit = null } = backendTemplate || {};
+    if (!dir) throw new Error('backend: the backend template is required (backendTemplate)');
+    const serverDir = path.join(projectDir, SERVER_DIR);
+    if (await fs.pathExists(serverDir)) throw new Error(`${SERVER_DIR}/ already exists in the project`);
+
+    // 1. move: a rename on the same file system, otherwise a copy and a removal
+    await fs.move(dir, serverDir);
+
+    // 2. generate
+    const appName = deriveServerAppName(projectName);
+    const serverPackage = serverPackageOf(packageName);
+    await generateBackend({ projectName, appName, packageName: serverPackage, sharing: true, sample: false }, {
+        projectDir: serverDir, templateRef: ref, templateCommit: commit, generatorVersion, now
+    });
+
+    // 3. the local server's folder is the project root's .local-server/
+    await writeLocalServerDir(serverDir);
+
+    // 4. leftovers
+    for (const leftover of SERVER_LEFTOVERS) await fs.remove(path.join(serverDir, leftover));
+    log.info(`✅ Server ready (${appName}, ${serverPackage})`);
+    return { appName, packageName: serverPackage, template: { repo, ref, commit } };
+}
+
+module.exports = { deriveServerAppName, placeServer, serverPackageOf, SERVER_DIR, LOCAL_SERVER_DIR_LINE, INCLUDE_SERVER_BUILD };

package/src/validate.js

@@ -4,6 +4,7 @@ const LIMITS = require('./limits');
 const { configureValidator } = require('./contract');
 const { parseGenerateBody } = require('./requestParser');
 const { normalizeFeaturesConfig } = require('./featuresConfig');
+const { serverPackageOf } = require('./serverFromBackend');
 
 // compile/target SDK come from the template (AppConfig.kt); a minSdk above its targetSdk cannot build
 function minSdkAboveTarget(minSdk, targetSdk) {
@@ -60,6 +61,13 @@ function validate(input, { limits = LIMITS, templateTargetSdk = null } = {}) {
             !PV.validateUrl(normalizedFeaturesConfig.networkBaseUrl)) {
             return fail(PV.messages.urlInvalid);
         }
+        // The backend's server package is the app's plus .server (server/ from the backend template)
+        if (normalizedFeaturesConfig.backend === true) {
+            const serverPackage = serverPackageOf(packageName);
+            if (!PV.validatePackageName(serverPackage) || !PV.validateMaxLength(serverPackage, PV.MAX_LENGTH_PACKAGE_NAME)) {
+                return fail(`packageName is too long for the server package (${serverPackage})`);
+            }
+        }
     }
 
     return {