@starci/hfs 5.2.0 → 5.4.0

package/sync/compile-guard.mjs

@@ -0,0 +1,189 @@
+// compile-guard.mjs - HFS_SYNC_GROUP_HELD: `starci app sync --execute` never writes a render that leaves the app uncompilable. Before it writes
+// a managed TypeScript source (or deletes a retired one), the side's own TypeScript compiles the app with the writes laid over the disk and
+// compares the diagnostics of every file they touch, and of every file that imports one, with the same files on disk. A managed group whose
+// writes add an error (a template that reads a name the app does not provide yet, or drops one the app still imports) is held whole: none
+// of its files is written, the rest of the render is, and the sync names the group, its files and the errors, so the app provides what the
+// render reads and runs sync again. A side whose TypeScript is not installed cannot be compiled; its writes go through and say so.
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
+/** The refusal code of a held group. */
+export const GROUP_HELD = 'HFS_SYNC_GROUP_HELD';
+/** The pseudo-group of the retired files a sync deletes. */
+export const RETIRED_GROUP = 'retired';
+/** How many errors a held group prints. */
+const SHOWN_ERRORS = 20;
+const SOURCE = /\.tsx?$/;
+/** Whether `file` (app-relative) is TypeScript source a side compiles. */
+export const isGuardedSource = (file) => SOURCE.test(file) && !file.endsWith('.d.ts') && (file.startsWith('be/') || file.startsWith('fe/'));
+/** The tsconfig that compiles an app-relative source: `be/tsconfig.json`, or the front-end app's or package's own; null when there is none. */
+export function projectOf(root, file) {
+    const parts = file.split('/');
+    const project = parts[0] === 'be' ? 'be/tsconfig.json' : parts.length > 3 ? `fe/${parts[1]}/${parts[2]}/tsconfig.json` : null;
+    return project !== null && fs.existsSync(path.join(root, project)) ? project : null;
+}
+/** One side's compilation: its compiler, options and root files, the overlay of writes keyed the way the host compares file names. */
+class Side {
+    #ts;
+    #root;
+    #options;
+    #rootNames;
+    #baseline = new Map();
+    #program;
+    constructor(ts, root, project) {
+        this.#ts = ts;
+        this.#root = root;
+        const file = path.join(root, project);
+        const read = ts.readConfigFile(file, ts.sys.readFile);
+        const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, path.dirname(file), { noEmit: true }, file);
+        this.#options = { ...parsed.options, noEmit: true };
+        this.#rootNames = parsed.fileNames;
+    }
+    /** The name the host compares: absolute, forward slashes, lower case where the file system ignores case. */
+    key(file) {
+        const absolute = path.resolve(this.#root, file).replaceAll('\\', '/');
+        return this.#ts.sys.useCaseSensitiveFileNames ? absolute : absolute.toLowerCase();
+    }
+    #host(overlay) {
+        const host = this.#ts.createCompilerHost(this.#options, true);
+        const { readFile, fileExists, getSourceFile } = host;
+        host.readFile = (name) => (overlay.has(this.key(name)) ? overlay.get(this.key(name)) ?? undefined : readFile.call(host, name));
+        host.fileExists = (name) => (overlay.has(this.key(name)) ? overlay.get(this.key(name)) !== null : fileExists.call(host, name));
+        host.getSourceFile = (name, language, onError, create) => {
+            if (!overlay.has(this.key(name)))
+                return getSourceFile.call(host, name, language, onError, create);
+            const text = overlay.get(this.key(name));
+            return text === null || text === undefined ? undefined : this.#ts.createSourceFile(name, text, language, true);
+        };
+        return host;
+    }
+    #programOf(overlay, added) {
+        const rootNames = [...this.#rootNames.filter((name) => overlay.get(this.key(name)) !== null), ...added];
+        return this.#ts.createProgram({ rootNames, options: this.#options, host: this.#host(overlay), ...(this.#program === undefined ? {} : { oldProgram: this.#program }) });
+    }
+    /** The files of the program that import one of `targets` (keys), each with the targets it imports. */
+    importers(targets, overlay) {
+        const host = this.#host(overlay);
+        const cache = this.#ts.createModuleResolutionCache(this.#root, (name) => this.key(name), this.#options);
+        const found = new Map();
+        for (const name of this.#rootNames) {
+            const text = host.readFile(name);
+            if (text === undefined)
+                continue;
+            for (const imported of this.#ts.preProcessFile(text, true, true).importedFiles) {
+                const resolved = this.#ts.resolveModuleName(imported.fileName, name, this.#options, host, cache).resolvedModule?.resolvedFileName;
+                if (resolved === undefined || !targets.has(this.key(resolved)))
+                    continue;
+                const into = found.get(this.key(name)) ?? new Set();
+                into.add(this.key(resolved));
+                found.set(this.key(name), into);
+            }
+        }
+        return found;
+    }
+    /** The errors of `files` (keys) as `path TScode message`, each file once, in the program with `overlay` laid over the disk. */
+    errors(files, overlay, added) {
+        const program = this.#programOf(overlay, added);
+        if (overlay.size === 0)
+            this.#program = program;
+        const byKey = new Map(program.getSourceFiles().map((source) => [this.key(source.fileName), source]));
+        const answer = new Map();
+        for (const file of files) {
+            const source = byKey.get(file);
+            const relative = path.relative(this.#root, source?.fileName ?? file).replaceAll('\\', '/');
+            const found = source === undefined ? [] : [...program.getSyntacticDiagnostics(source), ...program.getSemanticDiagnostics(source)];
+            answer.set(file, found.map((diagnostic) => `${relative}${source === undefined || diagnostic.start === undefined ? '' : `:${String(source.getLineAndCharacterOfPosition(diagnostic.start).line + 1)}`} TS${String(diagnostic.code)} ${this.#ts.flattenDiagnosticMessageText(diagnostic.messageText, ' ')}`));
+        }
+        return answer;
+    }
+    /** The errors of `files` on disk, computed once per file. */
+    baseline(files) {
+        const missing = files.filter((file) => !this.#baseline.has(file));
+        if (missing.length > 0)
+            for (const [file, found] of this.errors(missing, new Map(), []))
+                this.#baseline.set(file, found);
+        return new Map(files.map((file) => [file, this.#baseline.get(file) ?? []]));
+    }
+}
+/** An error without its line, so a line moved by the write is the same error. */
+const unplaced = (error) => error.replace(/^([^ ]*?):\d+ /, '$1 ');
+/** The errors of `after` that `before` does not hold, counted as a multiset of unplaced errors. */
+function added(before, after) {
+    const left = new Map();
+    for (const error of before)
+        left.set(unplaced(error), (left.get(unplaced(error)) ?? 0) + 1);
+    return after.filter((error) => {
+        const count = left.get(unplaced(error)) ?? 0;
+        left.set(unplaced(error), count - 1);
+        return count <= 0;
+    });
+}
+/** The held groups of one side: compile with every write of the groups still in play, hold the groups that add an error, again until none does. */
+function judgeSide(side, writes) {
+    const held = [];
+    let open = [...writes];
+    while (open.length > 0) {
+        const overlay = new Map(open.map((write) => [side.key(write.path), write.text]));
+        const groupOf = new Map(open.map((write) => [side.key(write.path), write.group]));
+        // An importer is found on the disk with the new files added, so the importer of a file the writes delete is found too.
+        const importers = side.importers(new Set(overlay.keys()), new Map([...overlay].filter(([, text]) => text !== null)));
+        const files = [...new Set([...[...overlay.keys()].filter((file) => overlay.get(file) !== null), ...importers.keys()])];
+        const before = side.baseline(files);
+        const after = side.errors(files, overlay, open.filter((write) => write.text !== null).map((write) => path.resolve(write.path)));
+        const errors = new Map();
+        for (const file of files) {
+            const fresh = added(before.get(file) ?? [], after.get(file) ?? []);
+            if (fresh.length === 0)
+                continue;
+            const groups = groupOf.has(file) ? [groupOf.get(file)] : [...(importers.get(file) ?? [])].map((target) => groupOf.get(target));
+            for (const group of groups)
+                errors.set(group, [...(errors.get(group) ?? []), ...fresh]);
+        }
+        if (errors.size === 0)
+            break;
+        for (const [group, found] of errors)
+            held.push({ group, files: open.filter((write) => write.group === group).map((write) => write.path), errors: [...new Set(found)] });
+        open = open.filter((write) => !errors.has(write.group));
+    }
+    return held;
+}
+/**
+ * The groups `starci app sync --execute` holds back at `root`: every write of a TypeScript source is compiled, per side, with the side's own
+ * TypeScript (`loadTs`, the app's install by default); a side with no tsconfig compiles nothing, a side whose TypeScript is not installed is
+ * named in `unchecked`.
+ */
+export function guardWrites(root, writes, loadTs = (dir) => loadTypescript(dir, root)) {
+    const verdict = { held: [], unchecked: [] };
+    const bySide = new Map();
+    for (const write of writes.filter((candidate) => isGuardedSource(candidate.path))) {
+        const project = projectOf(root, write.path);
+        if (project !== null)
+            bySide.set(project, [...(bySide.get(project) ?? []), { ...write, path: path.join(root, write.path) }]);
+    }
+    for (const [project, sideWrites] of bySide) {
+        const ts = loadTs(path.join(root, path.dirname(project)));
+        if (ts === null) {
+            verdict.unchecked.push(project);
+            continue;
+        }
+        for (const group of judgeSide(new Side(ts, root, project), sideWrites)) {
+            const relative = group.files.map((file) => path.relative(root, file).replaceAll('\\', '/'));
+            const known = verdict.held.find((entry) => entry.group === group.group);
+            if (known === undefined)
+                verdict.held.push({ ...group, files: relative });
+            else
+                verdict.held.splice(verdict.held.indexOf(known), 1, { group: group.group, files: [...known.files, ...relative], errors: [...known.errors, ...group.errors] });
+        }
+    }
+    return verdict;
+}
+/** The lines sync prints for a held group: what is held and why, the first errors, and what to do. */
+export function heldLines(group) {
+    const more = group.errors.length > SHOWN_ERRORS ? [`  ... ${String(group.errors.length - SHOWN_ERRORS)} more`] : [];
+    return [
+        `${GROUP_HELD} ${group.group}: ${String(group.files.length)} files not written, the render adds ${String(group.errors.length)} type errors to the app (${group.files.join(', ')})`,
+        ...group.errors.slice(0, SHOWN_ERRORS).map((error) => `  ${error}`),
+        ...more,
+        `  make the app provide what the render reads (each error names it), then run "npx --no-install starci app sync --execute" again`,
+    ];
+}

package/sync/hygiene.mjs

@@ -45,6 +45,8 @@ const PLAINTEXT_NAME = /(^|\/)(\.env(\..*)?|[^/]*\.(pem|key|identity|age))$/;
 /** The app root's work tree and stack tree, app-relative (`starci app check --staged` runs at the app root). */
 const WORK = '.starciwork/';
 const STACKS = '.starcistacks/';
+/** The committed check cache: written by the CLI, judged by what its files hold (secret-records.mjs through the secret judgement), never by a `secrets/` folder in its path. */
+const CACHE = '.starcistacks/cache/';
 const GUARDED = (file) => file.startsWith(WORK) || file.startsWith(STACKS);
 /** The subset of `files` git ignores (as if untracked), asked in one call: a Set of paths. */
 function ignoredAmong(cwd, files) {
@@ -67,7 +69,7 @@ export function hygieneFindings(files, ignored) {
         if (file.startsWith(WORK) && ignored.has(file)) {
             findings.push({ file, code: 'HFS_WORK_AGENT_DATA', message: 'is agent output, which .starciwork/.gitignore refuses; keep it in the scratchpad or the blob store' });
         }
-        if (file.startsWith(STACKS) && !/\.enc(?:\.yaml)?$/.test(file) && !file.endsWith('.env.example') && !file.endsWith('/secrets/.gitkeep')) {
+        if (file.startsWith(STACKS) && !file.startsWith(CACHE) && !/\.enc(?:\.yaml)?$/.test(file) && !file.endsWith('.env.example') && !file.endsWith('/secrets/.gitkeep')) {
             if (file.includes('/secrets/'))
                 findings.push({ file, code: 'HFS_PLAINTEXT_SECRET', message: 'sits under secrets/ but is not sealed; only <slug>.enc may be tracked' });
             else if (PLAINTEXT_NAME.test(file))

package/sync/index.d.mts

@@ -1,6 +1,7 @@
 import { type RepoView } from '../runtime/scripts/hfs/slots.mjs';
 import type { AppRepo } from '../runtime/scripts/hfs/slot-app-view.mjs';
 import type { Slot, SlotManifest } from '../runtime/scripts/hfs/manifest-shape.mjs';
+import { guardWrites, type GuardedWrite } from './compile-guard.mjs';
 import type { ImageApp } from './stack-images.mjs';
 export declare const TEMPLATES_DIR: string;
 /** The scopes a target is rendered for: the app root, then each side. */
@@ -22,6 +23,7 @@ export interface Target {
     template: string;
     mode: string;
     slot?: string;
+    group?: string;
     markdown?: boolean;
 }
 /** The markers around a managed block. */
@@ -39,6 +41,8 @@ export interface RenderedTarget {
     scripts?: Record<string, unknown>;
     markdown?: boolean | undefined;
     markers?: Markers;
+    /** The managed group of a slot's file (`managedBy`), which sync writes or holds whole (compile-guard.mjs). */
+    group?: string;
 }
 /** What comparing a rendered target with the disk answers. */
 export interface TargetCheck {
@@ -140,6 +144,8 @@ export declare function sonarScope(presets: Presets | null | undefined): {
     tests: string[];
     exclusions: string[];
 };
+/** The managed ESLint config at the app root that lints the root workspace packages. */
+export declare const PACKAGES_LINT_FILE = "eslint.config.mjs";
 export declare function appSource(root: string, { parseYaml, notices }?: {
     parseYaml?: ParseYaml | undefined;
     notices?: string[] | undefined;
@@ -227,9 +233,13 @@ export declare function renderRepo(root: string, { presets, parseYaml, notices,
 export declare function retiredFiles(root: string, hfs: {
     edition?: string;
 } | null | undefined): string[];
-export declare function runSync(argv: string[], { cwd, out, presets, parseYaml }?: {
+/** The writes of `targets` and the deletions of `retired` the compile guard judges: every file sync would change, with its managed group. */
+export declare function guardedWrites(root: string, targets: readonly RenderedTarget[], retired: readonly string[]): GuardedWrite[];
+export declare function runSync(argv: string[], { cwd, out, presets, parseYaml, loadTs }?: {
     cwd?: string;
     out?: (line: string) => unknown;
     presets?: Presets | undefined;
     parseYaml?: ParseYaml | undefined;
+    /** The TypeScript of a side folder the compile guard compiles with; the app's own install by default. */
+    loadTs?: Parameters<typeof guardWrites>[2];
 }): Promise<number>;

package/sync/index.mjs

@@ -29,6 +29,7 @@ import { feAppPackageName } from '../runtime/scripts/hfs/rules/monorepo.mjs';
 import { DEFAULT_PORT, NODE_IMAGE, dockerfilePath } from '../runtime/scripts/hfs/rules/docker.mjs';
 import { isFile } from '../runtime/scripts/lib/fs-kind.mjs';
 import { readDeclaredSonarKey } from './sonar-key.mjs';
+import { RETIRED_GROUP, guardWrites, heldLines, isGuardedSource } from './compile-guard.mjs';
 import { readDeclaredStack, stackWorkflowVariables } from './stack-images.mjs';
 import { DB_DOCKERFILE, DB_IMAGE_APP, RETIRED_DB_DOCKERFILE } from '../db/image.mjs';
 import { byCodeUnit } from '../report/order.mjs';
@@ -99,7 +100,7 @@ function slotTargets(slot, scope, edition, manifest, hasTemplate, enabled) {
         const template = managedTemplate(scope, group, file, hasTemplate);
         if (!template)
             throw new SyncError('HFS_SYNC_TEMPLATE_MISSING', `slot ${slot.id} manages ${file} for ${scope}, but templates/{${scope},common}/${group} has no template for it`);
-        return { path: file, template, mode: MODE_OF_GROUP[group] ?? 'file', slot: slot.id };
+        return { path: file, template, mode: MODE_OF_GROUP[group] ?? 'file', slot: slot.id, group };
     });
 }
 function unlistedTargets(scope, edition) {
@@ -237,6 +238,9 @@ export function sonarScope(presets) {
     const tests = preset.filter(glob => !glob.endsWith('/**'));
     return { tests, exclusions: [...new Set([...preset, '**/.next/**', '**/node_modules/**'])] };
 }
+/** The managed ESLint config at the app root that lints the root workspace packages. */
+export const PACKAGES_LINT_FILE = 'eslint.config.mjs';
+const LINE = '\n';
 const SOURCE_FILE = /\.[cm]?ts$/;
 const SOURCE_SKIPPED = new Set(['node_modules', 'dist', 'coverage']);
 /**
@@ -396,6 +400,30 @@ const moduleExclusions = (dirs) => dirs.flatMap(dir => [`${dir}/src/workbench/**
 function registryTargets(app, source) {
     return registryFiles(app.project, source?.modules ?? []).map((file) => ({ path: file.path, scope: APP_SCOPE, mode: 'file', content: file.content, hash: hashOf(file.content) }));
 }
+/**
+ * The root `eslint.config.mjs` of an app that has root workspace packages (packages/agent-sdk, packages/module-<name>, the registry): no side config
+ * reaches `packages/`, so this managed file lints their source by subpath. The back-end canon judges everything but the front-end subpaths
+ * (`src/workbench/` outside its contract, `src/public/`), the front-end canon and the selected Grammar family those, each over the package view of
+ * the app root. An app without a root package has no such file; the family factory for packages is the family's `<name>GrammarPackagesConfig`.
+ */
+function packagesLintTargets(app, source) {
+    if (!(source?.modules?.length || source?.otherPackages?.length))
+        return [];
+    const grammar = grammarLintFor(app.sides.fe.grammar);
+    const factory = grammar.package ? grammar.factory.replace(/Config$/, 'PackagesConfig') : null;
+    const content = [
+        'import { loadPackagesHfs as loadBePackages, starciBePackagesConfig } from "@starci/eslint-canon-be"',
+        'import { loadPackagesHfs as loadFePackages, starciFePackagesConfig } from "@starci/eslint-canon-fe"',
+        ...(grammar.package ? [`import { ${factory} } from "${grammar.package}"`] : []),
+        '',
+        'const be = loadBePackages(import.meta.url)',
+        'const fe = loadFePackages(import.meta.url)',
+        '',
+        `export default [...(await starciBePackagesConfig({ hfs: be })), ...starciFePackagesConfig({ hfs: fe })${grammar.package ? `, ...${factory}({ hfs: fe })` : ''}]`,
+        '',
+    ].join(LINE);
+    return [{ path: PACKAGES_LINT_FILE, scope: APP_SCOPE, mode: 'file', content, hash: hashOf(content) }];
+}
 export function variables(app, scope, presets, sonarKey, manifest = loadSlotManifest(), source = { files: [], read: () => '' }) {
     const stack = source.stack ?? { images: [], passEnv: [] };
     const fe = app.sides.fe;
@@ -429,7 +457,9 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
         typecheck: `${modulesFirst}npm run codegen --silent && tsc -p be/tsconfig.json && turbo run typecheck`,
         // The typed lint reads the types the fe packages declare (their dist), so the packages are built first.
         lintPrefix: `${modulesFirst}${packages ? 'npm run codegen --silent && turbo run build --filter=./fe/packages/* && ' : 'npm run codegen --silent && '}`,
-        moduleTests: modules.length ? ' && npm run test:modules' : '',
+        // The unit run, the back-end build and every CI job that imports a module package find it built (build:modules precedes them); the logic of a package is held at 100 per file by its own jest run, a step of the fast job.
+        modulesFirst,
+        moduleTestStep: modules.length ? '      - name: module packages\n        run: npm run test:modules\n' : '',
         nodeMajor: String(NODE_MAJOR),
         // The deploy server's age identity the restore workflow writes (stack/server-key.mjs owns the path).
         serverAgeIdentity: SERVER_AGE_IDENTITY,
@@ -503,7 +533,7 @@ function renderOnce(hfs, presets, { sonarKey, readTemplate = readBundled, manife
             declaredTargets.push({ path: 'README.md', mode: 'block', markdown: true, template: 'app/readme-badges/README.md' });
         const targets = declaredTargets
             .filter(target => !(app.edition === 'lite' && source?.workPresent === false && target.path === '.starciwork/.gitignore'));
-        return [...(scope === APP_SCOPE ? registryTargets(app, source) : []), ...targets.map((target) => {
+        return [...(scope === APP_SCOPE ? [...registryTargets(app, source), ...packagesLintTargets(app, source)] : []), ...targets.map((target) => {
                 const template = target.path === 'codecov.yml' && source?.quality?.codecov.enabled === false
                     ? '{{header}}\n# Codecov is disabled in the manifest.\ncodecov:\n  require_ci_to_pass: false\n'
                     : readTemplate(target.template);
@@ -519,7 +549,7 @@ function renderOnce(hfs, presets, { sonarKey, readTemplate = readBundled, manife
                 const markers = target.markdown ? { begin: '<!-- >>> starci app sync (managed block; do not edit) >>> -->', end: '<!-- <<< starci app sync <<< -->' } : { begin: BLOCK_BEGIN, end: BLOCK_END };
                 const spacing = target.markdown ? '\n' : '';
                 const managed = target.mode === 'block' ? `${markers.begin}\n${spacing}${trailingNewline(body)}${spacing}${markers.end}\n` : body;
-                return { path: where, scope, mode: target.mode, markdown: target.markdown, markers, content: managed, hash: hashOf(managed) };
+                return { path: where, scope, mode: target.mode, markdown: target.markdown, markers, content: managed, hash: hashOf(managed), ...(target.group === undefined ? {} : { group: target.group }) };
             })];
     });
 }
@@ -657,6 +687,8 @@ const LITE_RETIRED_DIRS = Object.freeze(['supabase/types']);
 /** The files a lite app's sync retires, each with the reason the dry run prints. */
 const LITE_RETIRED_FILES = Object.freeze({
     [RETIRED_DB_DOCKERFILE]: `the db image moved to ${DB_DOCKERFILE} (ruling lite-db-image-in-stacks)`,
+    'be/src/modules/domain/identity/persistence/entities/auth-user.entity.ts': 'the sign-in reaches accounts through the account doors (be/src/modules/domain/identity/persistence/account-doors.port.ts); the application role holds no grant on schema auth',
+    'be/src/modules/domain/identity/persistence/entities/auth-identity.entity.ts': 'the sign-in reaches accounts through the account doors (be/src/modules/domain/identity/persistence/account-doors.port.ts); the application role holds no grant on schema auth',
     '.github/workflows/db-deploy.yml': 'the stack deploy migrates the database (a verified backup, the expand migrations before the services, the contract migrations after the accept; ruling app-cicd-auto-deploy)',
 });
 /** Why a retired file goes: a retired file's own reason, else the folder's. */
@@ -683,6 +715,16 @@ export function retiredFiles(root, hfs) {
         walk(file);
     return found;
 }
+/** The writes of `targets` and the deletions of `retired` the compile guard judges: every file sync would change, with its managed group. */
+export function guardedWrites(root, targets, retired) {
+    const changed = checkTargets(root, targets).filter(result => result.status !== 'ok' && isGuardedSource(result.path));
+    const writes = changed.map((result) => {
+        const target = targets.find(candidate => candidate.path === result.path);
+        const file = path.join(root, target.path);
+        return { path: target.path, group: target.group ?? target.path, text: writtenContent(target, fs.existsSync(file) ? lf(fs.readFileSync(file, 'utf8')) : '') };
+    });
+    return [...writes, ...retired.map((file) => ({ path: file, group: RETIRED_GROUP, text: null }))];
+}
 /** `starci app sync [--execute] [--cwd <dir>]` at the app root: the dry run reports drift, --execute writes; returns 0 clean, 1 drift, 2 usage. */
 function syncOptions(argv) {
     const write = argv.includes('--execute');
@@ -707,7 +749,7 @@ function reportSyncCheck(root, targets, out, retired = []) {
     out(`starci app sync: ${results.length - bad.length} of ${results.length} in sync${bad.length ? '; run "npx --no-install starci app sync --execute"' : ''}`);
     return bad.length || retired.length ? 1 : 0;
 }
-export async function runSync(argv, { cwd = process.cwd(), out = (line) => process.stdout.write(`${line}\n`), presets, parseYaml } = {}) {
+export async function runSync(argv, { cwd = process.cwd(), out = (line) => process.stdout.write(`${line}\n`), presets, parseYaml, loadTs } = {}) {
     const options = syncOptions(argv);
     if (!options) {
         out('usage: starci app sync [--execute] [--cwd <dir>]');
@@ -723,18 +765,27 @@ export async function runSync(argv, { cwd = process.cwd(), out = (line) => proce
             for (const notice of new Set(notices))
                 out(notice);
         if (write) {
-            const written = writeTargets(root, targets);
+            const { held, unchecked } = guardWrites(root, guardedWrites(root, targets, retired), loadTs);
+            const holds = new Set(held.flatMap(group => group.files));
+            const free = targets.filter(target => !holds.has(target.path));
+            const written = writeTargets(root, free);
+            const removed = retired.filter(file => !holds.has(file));
             for (const file of written)
                 out(`wrote ${file}`);
-            for (const file of retired) {
+            for (const file of removed) {
                 fs.rmSync(path.join(root, file));
                 out(`removed ${file} (retired)`);
             }
             for (const dir of LITE_RETIRED_DIRS)
-                if (retired.length && fs.existsSync(path.join(root, dir)) && !fs.readdirSync(path.join(root, dir)).length)
+                if (removed.length && fs.existsSync(path.join(root, dir)) && !fs.readdirSync(path.join(root, dir)).length)
                     fs.rmdirSync(path.join(root, dir));
-            out(`starci app sync: ${written.length} written, ${targets.length - written.length} already in sync`);
-            return 0;
+            for (const project of unchecked)
+                out(`notice: the writes compiled by ${project} were not type-checked: its TypeScript is not installed (run npm install, then "npx --no-install starci app check")`);
+            for (const group of held)
+                for (const line of heldLines(group))
+                    out(line);
+            out(`starci app sync: ${written.length} written, ${free.length - written.length} already in sync${holds.size ? `, ${holds.size} held` : ''}`);
+            return held.length ? 1 : 0;
         }
         return reportSyncCheck(root, targets, out, retired);
     }

package/templates/app/auth-doors.sql.partial

@@ -0,0 +1,115 @@
+-- The account doors of a lite app: the only way app_be reaches auth.users and auth.identities (it holds no grant on schema auth). Eight
+-- SECURITY DEFINER functions with a pinned search_path, EXECUTE revoked from public and the browser roles and granted to app_be alone: an
+-- account comes back only for an exact address or id, a hash only for an exact address, and no door writes role or app metadata; the hash
+-- is written only by a new account and by be_auth_set_password.
+-- The text is the canon owner of the doors (templates/app/auth-doors.sql.partial); the back end calls them through persistence/account-doors.port.ts.
+
+-- Looks up an address in lower case; the bootstrap index serves email as written, not lower(email).
+create index if not exists users_email_lower_idx on auth.users (lower(email)) where is_anonymous = false;
+
+-- A person by sign-in address (lower-cased), with the stored bcrypt hash so the back end can verify it.
+CREATE FUNCTION public.be_auth_user_by_email(p_email text)
+    RETURNS TABLE(id uuid, email text, encrypted_password text, email_confirmed_at timestamp with time zone, disabled boolean)
+    LANGUAGE sql STABLE SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+  select u.id, u.email::text, u.encrypted_password::text, u.email_confirmed_at,
+         (u.deleted_at is not null or (u.banned_until is not null and u.banned_until > now()))
+    from auth.users u
+   where lower(u.email) = p_email and u.is_anonymous = false
+   order by u.created_at asc nulls last
+   limit 1;
+$$;
+
+-- One person by id.
+CREATE FUNCTION public.be_auth_user_by_id(p_user uuid)
+    RETURNS TABLE(id uuid, email text, last_sign_in_at timestamp with time zone, meta jsonb, disabled boolean)
+    LANGUAGE sql STABLE SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+  select u.id, u.email::text, u.last_sign_in_at, coalesce(u.raw_user_meta_data, '{}'::jsonb),
+         (u.deleted_at is not null or (u.banned_until is not null and u.banned_until > now()))
+    from auth.users u where u.id = p_user;
+$$;
+
+-- The person a Google account is linked to, if any.
+CREATE FUNCTION public.be_auth_user_by_google(p_provider_id text) RETURNS uuid
+    LANGUAGE sql STABLE SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+  select i.user_id from auth.identities i where i.provider = 'google' and i.provider_id = p_provider_id limit 1;
+$$;
+
+-- Creates a person; a null hash is an invited or Google-only account that has no password yet.
+CREATE FUNCTION public.be_auth_create_user(p_id uuid, p_email text, p_hash text, p_confirmed boolean, p_meta jsonb, p_now timestamp with time zone)
+    RETURNS uuid
+    LANGUAGE sql VOLATILE SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+  insert into auth.users (instance_id, id, aud, role, email, encrypted_password, email_confirmed_at, invited_at,
+                          raw_app_meta_data, raw_user_meta_data, created_at, updated_at)
+  values ('00000000-0000-0000-0000-000000000000', p_id, 'authenticated', 'authenticated', p_email, p_hash,
+          case when p_confirmed then p_now end, case when p_hash is null and not p_confirmed then p_now end,
+          '{"provider":"email","providers":["email"]}'::jsonb, p_meta, p_now, p_now)
+  returning id;
+$$;
+
+-- Links a Google account to a person.
+CREATE FUNCTION public.be_auth_link_google(p_user uuid, p_provider_id text, p_data jsonb, p_now timestamp with time zone) RETURNS void
+    LANGUAGE sql VOLATILE SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+  insert into auth.identities (provider_id, user_id, identity_data, provider, last_sign_in_at, created_at, updated_at)
+  values (p_provider_id, p_user, p_data, 'google', p_now, p_now, p_now)
+  on conflict (provider_id, provider) do update set last_sign_in_at = p_now, updated_at = p_now;
+$$;
+
+-- Records a sign-in; a verified Google address also confirms the mailbox; profile keys only fill what the person has not set.
+CREATE FUNCTION public.be_auth_touch_user(p_user uuid, p_now timestamp with time zone, p_confirm boolean, p_meta jsonb) RETURNS void
+    LANGUAGE sql VOLATILE SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+  update auth.users
+     set last_sign_in_at = p_now,
+         updated_at = p_now,
+         email_confirmed_at = case when p_confirm then coalesce(email_confirmed_at, p_now) else email_confirmed_at end,
+         raw_user_meta_data = p_meta || coalesce(raw_user_meta_data, '{}'::jsonb)
+   where id = p_user;
+$$;
+
+-- Stamps the confirmation of a mailbox (a spent confirmation link); a mailbox that is already confirmed keeps its date and the sign-in record is untouched.
+CREATE FUNCTION public.be_auth_confirm_user(p_user uuid, p_now timestamp with time zone) RETURNS void
+    LANGUAGE sql VOLATILE SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+  update auth.users set email_confirmed_at = coalesce(email_confirmed_at, p_now), updated_at = p_now where id = p_user;
+$$;
+
+-- Sets a new password hash; when p_confirm is true (a spent reset link proved the mailbox) the address is confirmed too.
+CREATE FUNCTION public.be_auth_set_password(p_user uuid, p_hash text, p_confirm boolean, p_now timestamp with time zone) RETURNS void
+    LANGUAGE sql VOLATILE SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+  update auth.users
+     set encrypted_password = p_hash,
+         email_confirmed_at = case when p_confirm then coalesce(email_confirmed_at, p_now) else email_confirmed_at end,
+         updated_at = p_now
+   where id = p_user;
+$$;
+
+REVOKE EXECUTE ON FUNCTION public.be_auth_user_by_email(text) FROM PUBLIC, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.be_auth_user_by_email(text) TO app_be;
+REVOKE EXECUTE ON FUNCTION public.be_auth_user_by_id(uuid) FROM PUBLIC, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.be_auth_user_by_id(uuid) TO app_be;
+REVOKE EXECUTE ON FUNCTION public.be_auth_user_by_google(text) FROM PUBLIC, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.be_auth_user_by_google(text) TO app_be;
+REVOKE EXECUTE ON FUNCTION public.be_auth_create_user(uuid, text, text, boolean, jsonb, timestamp with time zone) FROM PUBLIC, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.be_auth_create_user(uuid, text, text, boolean, jsonb, timestamp with time zone) TO app_be;
+REVOKE EXECUTE ON FUNCTION public.be_auth_link_google(uuid, text, jsonb, timestamp with time zone) FROM PUBLIC, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.be_auth_link_google(uuid, text, jsonb, timestamp with time zone) TO app_be;
+REVOKE EXECUTE ON FUNCTION public.be_auth_touch_user(uuid, timestamp with time zone, boolean, jsonb) FROM PUBLIC, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.be_auth_touch_user(uuid, timestamp with time zone, boolean, jsonb) TO app_be;
+REVOKE EXECUTE ON FUNCTION public.be_auth_confirm_user(uuid, timestamp with time zone) FROM PUBLIC, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.be_auth_confirm_user(uuid, timestamp with time zone) TO app_be;
+REVOKE EXECUTE ON FUNCTION public.be_auth_set_password(uuid, text, boolean, timestamp with time zone) FROM PUBLIC, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.be_auth_set_password(uuid, text, boolean, timestamp with time zone) TO app_be;

package/templates/app/ci-workflows/github/workflows/ci.yml

@@ -92,7 +92,7 @@ jobs:
         run: npm run typecheck
         env:
           NODE_OPTIONS: {{nodeOptions}}
-
+{{moduleTestStep}}
   lint:
     needs: plan
     if: ${{ needs.plan.outputs.checks == 'true' }}

package/templates/app/ci-workflows-lite/github/workflows/ci.yml

@@ -92,7 +92,7 @@ jobs:
         run: npm run typecheck
         env:
           NODE_OPTIONS: {{nodeOptions}}
-
+{{moduleTestStep}}
   lint:
     needs: plan
     if: ${{ needs.plan.outputs.checks == 'true' }}

package/templates/app/package-scripts/core.json

@@ -1,4 +1,4 @@
-    "build:be": "cd be && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+    "build:be": "{{modulesFirst}}cd be && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
     "build:fe": "{{buildFe}}",
     "codegen": "node scripts/codegen.mjs",
     "codegen:graphql": "node scripts/codegen.mjs --graphql",

package/templates/app/package-scripts/package.json

@@ -4,7 +4,7 @@
     {{appScripts}}
 {{> app/package-scripts/core.json}}
     "typecheck:tests": "tsc -p be/src/tests/tsconfig.json",
-    "test": "cd be && jest --selectProjects unit --coverage{{moduleTests}}",
+    "test": "{{modulesFirst}}cd be && jest --selectProjects unit --coverage",
     "test:integration": "npm run typecheck:tests && cd be && jest --selectProjects integration",
     "test:e2e": "npm run typecheck:tests && cd be && jest --selectProjects e2e",
     "test:contract": "npm run typecheck:tests && cd be && jest --selectProjects contract",

package/templates/app/package-scripts-lite/package.json

@@ -4,7 +4,7 @@
     {{appScripts}}
 {{> app/package-scripts/core.json}}
     "typecheck:tests": "tsc -p be/src/tests/tsconfig.json",
-    "test": "cd be && jest --selectProjects unit --coverage{{moduleTests}}",
+    "test": "{{modulesFirst}}cd be && jest --selectProjects unit --coverage",
     "test:integration": "npm run typecheck:tests && cd be && jest --selectProjects integration",
 {{> app/package-scripts/db.json}}
 {{backingScripts}}

package/templates/app/skeleton-lite/.starcistacks/application-stacks.yaml

@@ -58,8 +58,11 @@ environments:
         db: 54322
         api: 3001
         web: 3000
+        mail: 1025
+        mailui: 8025
       services:
         - {name: db, wait: healthy}
+        - {name: mail, wait: healthy}
       database:
         service: db
         port: db
@@ -97,6 +100,11 @@ environments:
             AUTH_WEB_ORIGIN: "http://localhost:${port.web}"
             AUTH_JWT_AUDIENCE: {{project}}
             AUTH_JWT_KEY_ID: dev-1
+            MAIL_HOST: 127.0.0.1
+            MAIL_PORT: "${port.mail}"
+            MAIL_SECURITY: none
+            MAIL_FROM: no-reply@{{project}}.example.invalid
+            MAIL_FROM_NAME: {{project}}
             STORAGE_ENDPOINT: "http://127.0.0.1:9000"
             STORAGE_REGION: us-east-1
             STORAGE_BUCKET: {{project}}-dev
@@ -120,6 +128,7 @@ environments:
       origins:
         - {name: web, url: "http://localhost:${port.web}"}
         - {name: api, url: "http://localhost:${port.api}"}
+        - {name: mail, url: "http://localhost:${port.mailui}"}
   production:
     status: supported
     runtime: docker-swarm

package/templates/app/skeleton-lite/.starcistacks/dev/README.md

@@ -2,7 +2,7 @@
 
 The dev environment is one command: `starci app stack up --env dev --execute`. It checks the machine, opens the dev custody, runs the setup
 commands, starts the dependencies in Docker Linux containers (the `db` service: the official postgres image plus pgvector, built from
-`.starcistacks/images/db/Dockerfile`), gives the environment its own database role, migrates, runs the seed, starts the api and web
+`.starcistacks/images/db/Dockerfile`; the `mail` service: Mailpit, the dev mail sink), gives the environment its own database role, migrates, runs the seed, starts the api and web
 processes natively and waits for readiness. What it runs is the `local` block of `environments.dev` in `.starcistacks/application-stacks.yaml`
 (PROJECT-STACKS-6 in contexts/project/stacks.md); this runbook never carries a docker command, an agent never runs docker by hand.
 
@@ -26,5 +26,7 @@ another environment.
 | down | `starci app stack down --env dev --execute`: ends the processes and stops the compose project; volumes and sealed values stay. |
 | verification | `starci app stack verify --env dev`: the declared liveness and readiness probes after a real start, then `npm run lint` from the app root. |
 
+**Mail.** The confirmation and reset mails of the sign-in go to the `mail` service on its SMTP port (`MAIL_HOST`, `MAIL_PORT`, `MAIL_SECURITY: none`: a plain channel that only the loopback sink accepts) and nothing leaves the machine. Open the web UI at the `mail` origin `up` prints (`http://localhost:8025` by default), sign up in the web app and follow the link from the message there. A deployed environment names a real SMTP server and `MAIL_SECURITY: starttls` or `tls`.
+
 The database volume `db-data` is rebuildable development data: `starci app db migrate` recreates its schema from `db/bootstrap.sql` and
 `db/migrations`. Key names of the environment are in `.starcistacks/dev/runtime/env/KEYS.md`.