@starci/hfs 5.1.0 → 5.2.0

package/stack/local-up.mjs

@@ -0,0 +1,166 @@
+// local-up.mjs - `starci app stack up --env <dev env> [--execute]`: the one command that brings the whole dev environment up (PROJECT-STACKS-6).
+// Order: host prerequisites, dev custody, setup (install, codegen), compose services and their health, the environment's own database role,
+// migrations with a receipt, seed, native app processes, readiness, origins. Idempotent: what runs is kept, what changed is converged.
+// A dry run prints the plan. It never generates a replacement secret, never removes a volume and touches only its own compose project.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { firstLine } from './context.mjs';
+import { failure, refusal } from './errors.mjs';
+import { missingKeys, missingStep, openCustody } from './local-custody.mjs';
+import { hostRefusal, preflight, runSetup } from './local-prepare.mjs';
+import { DEFAULT_TIMEOUT_SECONDS, makeDataDirectories, commandDigest, compose, composeValues, databaseUrl, isAlive, probe, runCommand, runEnvironment, serviceReady, startProcess, stateOf, waitFor } from './local-run.mjs';
+import { readRecord, writeRecord } from './local-state.mjs';
+const SAFE_PASSWORD = /^[A-Za-z0-9_-]{8,}$/u;
+/** The digest of the migration folder (names and contents): what a migrate receipt records. */
+export function migrationsDigest(repoRoot) {
+    const directory = path.join(repoRoot, 'db', 'migrations');
+    const hash = crypto.createHash('sha256');
+    let names = [];
+    try {
+        names = fs.readdirSync(directory).filter((name) => name.endsWith('.sql')).sort();
+    }
+    catch {
+        return 'none';
+    }
+    for (const name of names)
+        hash.update(name).update(fs.readFileSync(path.join(directory, name)));
+    return hash.digest('hex').slice(0, 16);
+}
+/** Creates the environment's own login role and database if absent and sets its password (psql in the db container, SQL on stdin, never argv). */
+async function provisionDatabase(ctx, local, custody) {
+    const database = local.database;
+    if (!database)
+        return 'database: none declared';
+    const password = custody.values.get(database.password.key) ?? '';
+    if (!SAFE_PASSWORD.test(password))
+        throw refusal('STACK_LOCAL_DB_PASSWORD', `${database.password.key} must be at least 8 characters of letters, digits, dash and underscore (the generated password kind is); the owner replaces it with secret unset and secret init`);
+    const sql = [
+        `DO $do$ BEGIN IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = '${database.role}') THEN CREATE ROLE "${database.role}" LOGIN SUPERUSER PASSWORD '${password}'; ELSE ALTER ROLE "${database.role}" LOGIN SUPERUSER PASSWORD '${password}'; END IF; END $do$;`,
+        `SELECT 'CREATE DATABASE "${database.name}" OWNER "${database.role}"' WHERE NOT EXISTS (SELECT FROM pg_database WHERE datname = '${database.name}')\\gexec`,
+        '',
+    ].join('\n');
+    const result = await compose(ctx, local, ['exec', '-T', database.service, 'psql', '-v', 'ON_ERROR_STOP=1', '-U', database.adminUser, '-d', 'postgres'], { values: composeValues(local, custody), input: sql });
+    if (result.status !== 0)
+        throw failure('STACK_LOCAL_DB_ROLE', `could not provision the role ${database.role}: ${(result.stderr.trim().split(/\r?\n/u)[0] ?? '').replaceAll(password, '[redacted]')}`);
+    return `database: role ${database.role} and database ${database.name} ready on port ${local.ports[database.port]}`;
+}
+/** Gives the app role the migrations created its own password for this environment (cluster roles are never shared: the db container is this environment's alone). */
+async function appRolePassword(ctx, local, custody) {
+    const database = local.database;
+    if (!database?.appRole || !database.appPassword)
+        return '';
+    const password = custody.values.get(database.appPassword.key) ?? '';
+    if (!SAFE_PASSWORD.test(password))
+        throw refusal('STACK_LOCAL_DB_PASSWORD', `${database.appPassword.key} must be at least 8 characters of letters, digits, dash and underscore`);
+    const sql = `DO $do$ BEGIN IF EXISTS (SELECT FROM pg_roles WHERE rolname = '${database.appRole}') THEN ALTER ROLE "${database.appRole}" LOGIN PASSWORD '${password}'; ELSE RAISE EXCEPTION 'role ${database.appRole} does not exist: the migrations create it'; END IF; END $do$;\n`;
+    const result = await compose(ctx, local, ['exec', '-T', database.service, 'psql', '-v', 'ON_ERROR_STOP=1', '-U', database.adminUser, '-d', database.name], { values: composeValues(local, custody), input: sql });
+    if (result.status !== 0)
+        throw failure('STACK_LOCAL_DB_ROLE', `could not set the password of ${database.appRole}: ${(result.stderr.trim().split(/\r?\n/u)[0] ?? '').replaceAll(password, '[redacted]')}`);
+    return `, ${database.appRole} password set`;
+}
+/** Migrates through `starci app db migrate` in this process; the URL stays in the environment of that call. */
+async function migrate(ctx, local, custody, deps) {
+    const database = local.database;
+    const url = databaseUrl(local, custody);
+    if (!database || url === null)
+        return 'migrate: no database declared';
+    const container = firstLine((await compose(ctx, local, ['ps', '-q', database.service])).stdout);
+    const env = { ...ctx.env, DATABASE_URL: url, STARCI_DB_CONTAINER: container };
+    const run = deps.migrate ?? (async (urlEnv, environment, cwd) => {
+        const { main } = await import('../src/main.mjs');
+        return main(['db', 'migrate', '--db-url-env', urlEnv, '--execute'], { cwd, env: environment, stdout: () => { }, stderr: () => { } });
+    });
+    const code = await run('DATABASE_URL', env, local.repoRoot);
+    if (code !== 0)
+        throw failure('STACK_LOCAL_MIGRATE', `starci app db migrate exited ${code}; run it with --db-url-env DATABASE_URL to read its report`);
+    const dir = stateOf(ctx, local);
+    const record = readRecord(dir);
+    record.receipts.migrate = { at: new Date(ctx.now()).toISOString(), digest: migrationsDigest(local.repoRoot) };
+    writeRecord(dir, record);
+    return `migrate: applied, receipt ${record.receipts.migrate.digest}${await appRolePassword(ctx, local, custody)}`;
+}
+/** Runs the seed commands once each (a receipt keyed by the command's digest); the seed owns its idempotence beyond that. */
+async function seed(ctx, local, custody, after) {
+    const dir = stateOf(ctx, local);
+    const record = readRecord(dir);
+    const out = [];
+    for (const run of local.seed.filter((item) => item.after === after)) {
+        if (record.receipts.seed[run.name]?.digest === commandDigest(run)) {
+            out.push(`seed ${run.name}: already done`);
+            continue;
+        }
+        await runCommand(ctx, local, run, runEnvironment(ctx, local, run, custody, 'owner'));
+        record.receipts.seed[run.name] = { at: new Date(ctx.now()).toISOString(), digest: commandDigest(run) };
+        writeRecord(dir, record);
+        out.push(`seed ${run.name}: done`);
+    }
+    return out;
+}
+/** Starts each native process that is not already running. */
+function startProcesses(ctx, local, custody, deps) {
+    const dir = stateOf(ctx, local);
+    const record = readRecord(dir);
+    const out = [];
+    const alive = deps.alive ?? isAlive;
+    for (const run of local.processes) {
+        const known = record.processes[run.name];
+        if (known && alive(known.pid)) {
+            out.push(`process ${run.name}: running (pid ${known.pid})`);
+            continue;
+        }
+        const pid = startProcess(ctx, local, run, runEnvironment(ctx, local, run, custody, 'app'));
+        record.processes[run.name] = { pid, startedAt: new Date(ctx.now()).toISOString(), port: run.port === null ? null : (local.ports[run.port] ?? null) };
+        out.push(`process ${run.name}: started (pid ${pid})`);
+    }
+    record.ports = { ...local.ports };
+    writeRecord(dir, record);
+    return out;
+}
+/** The plan a dry run prints. */
+function plan(local, missing) {
+    return [
+        `plan custody: ${missing.length ? `missing ${missing.join(', ')}: ${missingStep(local, missing)}` : 'open the sealed dev values into host-local files'}`,
+        ...local.setup.map((run) => `plan setup ${run.name}: ${run.argv.join(' ')}`),
+        `plan services: ${local.services.map((service) => `${service.name} (wait ${service.wait})`).join(', ')}`,
+        ...(local.database ? [`plan database: own role ${local.database.role}, database ${local.database.name}, then starci app db migrate`] : []),
+        ...local.seed.map((run) => `plan seed ${run.name}: ${run.argv.join(' ')}`),
+        ...local.processes.map((run) => `plan process ${run.name}: ${run.argv.join(' ')}`),
+        ...local.ready.map((row) => `plan ready ${row.name}: ${row.url}`),
+    ];
+}
+/** `up` for a dev environment. */
+export async function upLocal(ctx, local, { execute = false, timeoutSeconds = DEFAULT_TIMEOUT_SECONDS } = {}, deps = {}) {
+    const host = await preflight(ctx, local, deps);
+    if (!host.ok)
+        return hostRefusal(host.lines);
+    const missing = missingKeys(local);
+    if (!execute)
+        return { ok: missing.length === 0, lines: [...host.lines, ...plan(local, missing), 'dry run: nothing was started; arm it with --execute'], data: { rows: host.rows } };
+    const lines = [...host.lines];
+    const custody = openCustody(ctx, local);
+    lines.push(`custody: ${custody.values.size} key file(s) in the host-local directory`);
+    lines.push(...await runSetup(ctx, local, custody));
+    makeDataDirectories(ctx, local);
+    const values = composeValues(local, custody);
+    const started = await compose(ctx, local, ['up', '-d', ...local.services.map((service) => service.name)], { values, heavy: true, label: 'compose up' });
+    if (started.status !== 0)
+        throw failure('STACK_LOCAL_COMPOSE', `docker compose up failed: ${(started.stderr.trim().split(/\r?\n/u)[0] ?? '').slice(0, 200)}`);
+    const deadline = ctx.now() + timeoutSeconds * 1000;
+    for (const service of local.services) {
+        const ready = await serviceReady(ctx, local, service.name, deadline, deps);
+        lines.push(`service ${ready.detail}`);
+        if (!ready.ok)
+            throw failure('STACK_LOCAL_SERVICE', `${service.name} did not become ready in ${timeoutSeconds}s (${ready.detail}); read it with: starci app stack logs --env ${local.env} --service ${service.name}`);
+    }
+    lines.push(await provisionDatabase(ctx, local, custody), await migrate(ctx, local, custody, deps), ...await seed(ctx, local, custody, 'migrate'), ...startProcesses(ctx, local, custody, deps));
+    for (const row of local.ready) {
+        const result = await waitFor(ctx, deadline, () => probe(ctx, local, row));
+        lines.push(`${result.ok ? 'ok    ' : 'FAIL  '}ready ${result.detail}`);
+        if (!result.ok)
+            throw failure('STACK_LOCAL_READY', `${row.name} is not ready: ${result.detail}; read a process log with: starci app stack logs --env ${local.env} --service ${local.processes.map((run) => run.name).join('|')}`);
+    }
+    lines.push(...await seed(ctx, local, custody, 'ready'));
+    lines.push(...local.origins.map((origin) => `origin ${origin.name}: ${origin.url.replaceAll(/\$\{port\.([a-z][a-z0-9-]*)\}/gu, (_whole, name) => String(local.ports[name]))}`));
+    return { ok: true, lines, data: { origins: local.origins } };
+}

package/stack/local-verify.d.mts

@@ -0,0 +1,6 @@
+import type { StackContext } from './context.mjs';
+import type { ActionResult } from './remote.mjs';
+import type { LocalConfig } from './local-config.mjs';
+import type { LocalDeps } from './local-run.mjs';
+/** `verify` for a dev environment. */
+export declare function verifyLocal(ctx: StackContext, local: LocalConfig, _options?: Record<string, unknown>, deps?: LocalDeps): Promise<ActionResult>;

package/stack/local-verify.mjs

@@ -0,0 +1,21 @@
+import { refusal } from './errors.mjs';
+import { isAlive, probe, stateOf } from './local-run.mjs';
+import { readRecord } from './local-state.mjs';
+/** `verify` for a dev environment. */
+export async function verifyLocal(ctx, local, _options = {}, deps = {}) {
+    if (local.verify.length === 0)
+        throw refusal('STACK_LOCAL_VERIFY_UNDECLARED', `environment ${local.env} declares no local.verify journey: a liveness probe alone is not verification`);
+    const record = readRecord(stateOf(ctx, local));
+    const alive = deps.alive ?? isAlive;
+    const down = local.processes.filter((run) => !(record.processes[run.name] && alive(record.processes[run.name].pid)));
+    if (down.length)
+        return { ok: false, lines: [`FAIL  ${down.map((run) => run.name).join(', ')} not running: start the environment with starci app stack up --env ${local.env} --execute`] };
+    const lines = [];
+    let ok = true;
+    for (const row of local.verify) {
+        const result = await probe(ctx, local, row);
+        ok &&= result.ok;
+        lines.push(`${result.ok ? 'ok    ' : 'FAIL  '}${result.detail}`);
+    }
+    return { ok, lines, data: { checked: local.verify.length } };
+}

package/sync/index.d.mts

@@ -64,6 +64,8 @@ export interface AppSourceFacts {
     read: (file: string) => string;
     workPresent: boolean;
     hasImage: (file: string) => boolean;
+    modules?: readonly string[];
+    otherPackages?: readonly string[];
     stack: any;
     quality: any;
     badges: string;
@@ -138,12 +140,6 @@ export declare function sonarScope(presets: Presets | null | undefined): {
     tests: string[];
     exclusions: string[];
 };
-/**
- * The be source of the app at `root` the coverage components read: { files, read }, `files` be-relative posix paths of every `*.ts` file under
- * be/apps and be/src (build output and dependencies skipped) and `read` their text. `workPresent` records whether the optional
- * lite brand tree exists, so sync can preserve its absence. `hasImage` identifies authored optional Dockerfiles without reading
- * their content. An app with no be folder has no source files.
- */
 export declare function appSource(root: string, { parseYaml, notices }?: {
     parseYaml?: ParseYaml | undefined;
     notices?: string[] | undefined;
@@ -178,7 +174,7 @@ export declare function jestCoverageSource(coverage: {
  * `docker:build:<app>` builds the image of one app (the exact command its Dockerfile header states, tag `<project>/<app>:dev`) and
  * `docker:build` builds every image, one after the other, never pushing.
  */
-export declare function appScripts(app: ResolvedApp, source: Partial<Pick<AppSourceFacts, 'hasImage'>> | undefined): string;
+export declare function appScripts(app: ResolvedApp, source: Partial<Pick<AppSourceFacts, 'hasImage' | 'modules'>> | undefined): string;
 /** The stylesheets of the fe side the CSS canon judges, relative to fe/: every app and every workspace package (slot fe.route, fe.package.*). */
 export declare const STYLE_GLOB = "{apps,packages}/*/src/**/*.css";
 /** The apps images.yml builds (one matrix entry per declared app): name and Dockerfile, be then fe, then a lite app's db image. */
@@ -192,14 +188,13 @@ export declare function imageFiles(app: ResolvedApp, source?: Partial<Pick<AppSo
     path: string;
     content: string;
 }[];
-/** Every value a template of `scope` can name, derived from hfs.json and the presets. */
 export declare function variables(app: ResolvedApp, scope: string, presets: Presets | null | undefined, sonarKey: string | null | undefined, manifest?: SlotManifest, source?: Pick<AppSourceFacts, 'files' | 'read'> & Partial<AppSourceFacts>): Record<string, string>;
 /**
- * The managed content of every target of the app: [{ path, mode, content, hash, scope }], paths app-relative (a side's targets under
- * its folder); a scripts target also carries `scripts`, the parsed block. `sonarKey` is the key the be side's stack declaration
- * names; without one the key is the project.
+ * The rendered targets of an app declaration. Without source facts the app counts the back-end source files its own targets
+ * render (the managed sign-in glue), as a check reading the disk after the targets are written does, so a render of a declaration
+ * alone is already in sync with itself.
  */
-export declare function renderTargets(hfs: unknown, presets: Presets | null | undefined, { sonarKey, readTemplate, manifest, source }?: {
+export declare function renderTargets(hfs: unknown, presets: Presets | null | undefined, options?: {
     sonarKey?: string | null | undefined;
     readTemplate?: (name: string) => string;
     manifest?: SlotManifest;
@@ -212,6 +207,12 @@ export declare function writtenContent(target: RenderedTarget, existing: string
 export declare function writeTargets(root: string, targets: readonly RenderedTarget[]): string[];
 /** The hfs.json object of the app at `root` (validated), or a SyncError. */
 export declare function loadHfs(root: string, manifest?: SlotManifest): Record<string, any>;
+/**
+ * The source facts as they stand once the rendered back-end source files are on disk: a managed `.ts` target of the be side counts as a
+ * file of the app (and reads as its render), so the CI shard count and the coverage scope that count or read the source name the same
+ * files before and after the targets are written, and one sync leaves the app in sync.
+ */
+export declare function settleSource(source: AppSourceFacts, targets: readonly RenderedTarget[]): AppSourceFacts;
 /** The rendered targets of the app at `root`: its hfs.json, the Sonar key the be side's stack declaration names, the presets it installs. */
 export declare function renderRepo(root: string, { presets, parseYaml, notices, manifest }?: {
     presets?: Presets | undefined;

package/sync/index.mjs

@@ -34,6 +34,7 @@ import { DB_DOCKERFILE, DB_IMAGE_APP, RETIRED_DB_DOCKERFILE } from '../db/image.
 import { byCodeUnit } from '../report/order.mjs';
 import { isRuntimeExampleApp } from '../runtime/scripts/lib/runtime-example.mjs';
 import { ciWorkflowCommands } from './ci-commands.mjs';
+import { MODULE_PREFIX, moduleNames, registryFiles } from '../scaffold/module-registry.mjs';
 import { dependabotUpdates, hasDeclaredServices, readDeclaredQuality, readDeclaredBadges, sonarHostLine } from './quality-services.mjs';
 import { qualityServices } from '../runtime/scripts/hfs/ci-declaration.mjs';
 import { grammarLintFor } from '../runtime/scripts/lib/grammar-lint.mjs';
@@ -244,6 +245,16 @@ const SOURCE_SKIPPED = new Set(['node_modules', 'dist', 'coverage']);
  * lite brand tree exists, so sync can preserve its absence. `hasImage` identifies authored optional Dockerfiles without reading
  * their content. An app with no be folder has no source files.
  */
+/** The folders of `packages/` that are neither a module package nor the registry. */
+function otherPackages(root) {
+    try {
+        return fs.readdirSync(path.join(root, 'packages'), { withFileTypes: true })
+            .filter(entry => entry.isDirectory() && !entry.name.startsWith(MODULE_PREFIX) && entry.name !== 'modules').map(entry => entry.name).sort(byCodeUnit);
+    }
+    catch {
+        return [];
+    }
+}
 export function appSource(root, { parseYaml, notices } = {}) {
     const files = [];
     const walk = (dir) => {
@@ -267,6 +278,7 @@ export function appSource(root, { parseYaml, notices } = {}) {
     for (const dir of ['apps', 'src'])
         walk(dir);
     return { runtimeExample: isRuntimeExampleApp(root), files: files.sort(byCodeUnit), read: (file) => fs.readFileSync(path.join(root, 'be', file), 'utf8'),
+        modules: moduleNames(root), otherPackages: otherPackages(root),
         workPresent: fs.existsSync(path.join(root, '.starciwork')), hasImage: (file) => isFile(path.join(root, file), { followLinks: false }),
         stack: readDeclaredStack(root, { parseYaml }), quality: readDeclaredQuality(root, { parseYaml }),
         badges: readDeclaredBadges(root, { parseYaml, notices }),
@@ -321,6 +333,7 @@ export function appScripts(app, source) {
         }),
         ...fe.map(entry => line(`start:${entry.name}`, `npm run start -w ${workspace(entry)}`)),
         ...(app.edition !== 'lite' && app.optionalSlots.includes('app.browser') ? [line('test:browser', 'playwright test -c browser/playwright.config.ts')] : []),
+        ...(source?.modules?.length ? [line('build:modules', 'turbo run build --filter=./packages/*'), line('test:modules', 'turbo run test --filter=./packages/module-*')] : []),
         line('docker:build', images.map(image => `npm run docker:build:${image.entry.name}`).join(' && ')),
         ...images.map(image => line(`docker:build:${image.entry.name}`, imageCommand(image))),
     ].join('\n    ');
@@ -377,6 +390,12 @@ export function imageFiles(app, source) {
     });
 }
 /** Every value a template of `scope` can name, derived from hfs.json and the presets. */
+/** What a module package keeps out of the measured scope: its workbench (drawn with Grammar, a front end has no tests) and its specs. The logic of its template and manifest is measured. */
+const moduleExclusions = (dirs) => dirs.flatMap(dir => [`${dir}/src/workbench/**`, `${dir}/src/**/index.ts`]);
+/** The managed files of the registry package for the module packages the app has (empty when it has none). */
+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) }));
+}
 export function variables(app, scope, presets, sonarKey, manifest = loadSlotManifest(), source = { files: [], read: () => '' }) {
     const stack = source.stack ?? { images: [], passEnv: [] };
     const fe = app.sides.fe;
@@ -384,6 +403,10 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
     const lite = app.edition === 'lite';
     const providers = (app.sides.be.connections ?? []).map(connection => connection.provider);
     const quality = source.quality ?? qualityServices({});
+    const modules = source.modules ?? [];
+    const moduleDirs = modules.map(name => `packages/${MODULE_PREFIX}${name}`);
+    // The module packages are built before anything imports them (typecheck, lint, the fe build and the be run all follow the registry).
+    const modulesFirst = modules.length ? 'npm run build:modules --silent && ' : '';
     const grammarLint = scope === 'fe' ? grammarLintFor(fe.grammar) : null;
     return {
         header: HEADER(scope),
@@ -401,11 +424,12 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
         // A lite app's declared Redis (sides.be.backing, ruling:R212/case-10) runs in development as one container of its pinned image.
         backingScripts: lite && (app.sides.be.backing ?? []).includes('redis') ? redisDevText(app.project) : '',
         // turbo builds every fe app workspace; ^build (turbo.json) builds the packages each app imports first, and caches both.
-        buildFe: 'npm run codegen --silent && turbo run build --filter=./fe/apps/*',
+        buildFe: `${modulesFirst}npm run codegen --silent && turbo run build --filter=./fe/apps/*`,
         // The be side with its tsc; every fe workspace with its own typecheck script through turbo (the packages are built first: ^build).
-        typecheck: 'npm run codegen --silent && tsc -p be/tsconfig.json && turbo run typecheck',
+        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: packages ? 'npm run codegen --silent && turbo run build --filter=./fe/packages/* && ' : 'npm run codegen --silent && ',
+        lintPrefix: `${modulesFirst}${packages ? 'npm run codegen --silent && turbo run build --filter=./fe/packages/* && ' : 'npm run codegen --silent && '}`,
+        moduleTests: modules.length ? ' && npm run test:modules' : '',
         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,
@@ -415,19 +439,19 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
         sonarHostLine: sonarHostLine(quality.sonar),
         sonarExclusions: sonarScope(presets).exclusions.join(','),
         sonarTestInclusions: sonarScope(presets).tests.join(','),
-        sonarSources: ['be/apps', 'be/src', 'fe/apps', ...(packages ? ['fe/packages'] : [])].join(','),
+        sonarSources: ['be/apps', 'be/src', 'fe/apps', ...(packages ? ['fe/packages'] : []), ...moduleDirs.map(dir => `${dir}/src`)].join(','),
         lcovReport: LCOV_REPORT,
         cpdExclusions: SONAR_CPD_EXCLUSIONS.join(','),
         ...ciWorkflowCommands(source, LCOV_REPORT, source.qualityDeclared === false ? undefined : source.quality, { app, packages }),
         // The coverage scope is the same in both editions: lite measures exactly what full measures (ruling:R212/case-1, amended by ruling:R212/case-4).
         jestCoverage: scope === 'be' ? jestCoverageSource(jestCoverage(manifest, providers)) : '',
-        coverageExclusions: scope === APP_SCOPE ? sonarCoverageExclusions(manifest, providers).join(',') : '',
-        codecovExclusions: scope === APP_SCOPE ? sonarCoverageExclusions(manifest, providers).map(glob => `  - ${JSON.stringify(glob)}`).join('\n') : '',
-        codecovPaths: scope === APP_SCOPE ? codecovPaths(manifest, providers).map(glob => `          - ${JSON.stringify(glob)}`).join('\n') : '',
+        coverageExclusions: scope === APP_SCOPE ? [...sonarCoverageExclusions(manifest, providers), ...moduleExclusions(moduleDirs)].join(',') : '',
+        codecovExclusions: scope === APP_SCOPE ? [...sonarCoverageExclusions(manifest, providers), ...moduleExclusions(moduleDirs)].map(glob => `  - ${JSON.stringify(glob)}`).join('\n') : '',
+        codecovPaths: scope === APP_SCOPE ? [...codecovPaths(manifest, providers), ...moduleDirs.flatMap(dir => [`${dir}/src/manifest/**`, `${dir}/src/template/**`])].map(glob => `          - ${JSON.stringify(glob)}`).join('\n') : '',
         codecovComponents: scope === APP_SCOPE ? componentsYaml(coverageComponents(manifest, { ...source, apps: app.sides.be.apps, providers })) : '',
         codecovTarget: quality.codecov.target,
         dependabotUpdates: dependabotUpdates(quality.dependabot),
-        tsconfigPaths: ['be/tsconfig.json', ...fe.apps.map(entry => `fe/apps/${entry.name}/tsconfig.json`), ...(packages ? ['fe/packages/*/tsconfig.json'] : [])].join(','),
+        tsconfigPaths: ['be/tsconfig.json', ...fe.apps.map(entry => `fe/apps/${entry.name}/tsconfig.json`), ...(packages ? ['fe/packages/*/tsconfig.json'] : []), ...moduleDirs.map(dir => `${dir}/tsconfig.json`)].join(','),
         styleGlob: STYLE_GLOB,
         grammarLintImport: grammarLint?.package ? `import { ${grammarLint.factory} } from "${grammarLint.package}"` : '',
         grammarLintExport: grammarLint?.package ? `export default [...starciFeConfig({ hfs }), ...${grammarLint.factory}({ hfs })]` : 'export default starciFeConfig({ hfs })',
@@ -446,12 +470,24 @@ function parseScripts(text) {
         return null;
     }
 }
+/**
+ * The rendered targets of an app declaration. Without source facts the app counts the back-end source files its own targets
+ * render (the managed sign-in glue), as a check reading the disk after the targets are written does, so a render of a declaration
+ * alone is already in sync with itself.
+ */
+export function renderTargets(hfs, presets, options = {}) {
+    const first = renderOnce(hfs, presets, options);
+    if (options.source !== undefined)
+        return first;
+    const settled = settleSource({ files: [], read: () => '' }, first); // reason: the settled facts name only the rendered source files; every other fact stays absent as without source
+    return settled.files.length === 0 ? first : renderOnce(hfs, presets, { ...options, source: settled });
+}
 /**
  * The managed content of every target of the app: [{ path, mode, content, hash, scope }], paths app-relative (a side's targets under
  * its folder); a scripts target also carries `scripts`, the parsed block. `sonarKey` is the key the be side's stack declaration
  * names; without one the key is the project.
  */
-export function renderTargets(hfs, presets, { sonarKey, readTemplate = readBundled, manifest = loadSlotManifest(), source } = {}) {
+function renderOnce(hfs, presets, { sonarKey, readTemplate = readBundled, manifest = loadSlotManifest(), source } = {}) {
     const app = validateHfs(hfs, manifest);
     const hasTemplate = (name) => { try {
         return readTemplate(name) !== undefined;
@@ -467,24 +503,24 @@ export function renderTargets(hfs, presets, { sonarKey, readTemplate = readBundl
             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 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);
-            const body = trailingNewline(render(template, vars, readTemplate));
-            const where = onSide(scope, target.path);
-            if (target.mode === 'scripts') {
-                const scripts = parseScripts(body);
-                if (!scripts)
-                    throw new SyncError('HFS_SYNC_TEMPLATE_VARIABLE', `the rendered ${target.template} has no scripts object`);
-                const content = scriptsText(scripts);
-                return { path: where, scope, mode: 'scripts', content, hash: hashOf(content), scripts };
-            }
-            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 [...(scope === APP_SCOPE ? registryTargets(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);
+                const body = trailingNewline(render(template, vars, readTemplate));
+                const where = onSide(scope, target.path);
+                if (target.mode === 'scripts') {
+                    const scripts = parseScripts(body);
+                    if (!scripts)
+                        throw new SyncError('HFS_SYNC_TEMPLATE_VARIABLE', `the rendered ${target.template} has no scripts object`);
+                    const content = scriptsText(scripts);
+                    return { path: where, scope, mode: 'scripts', content, hash: hashOf(content), scripts };
+                }
+                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) };
+            })];
     });
 }
 // The part of a file sync manages: all of it, all of it but the verb's section, the marked block, or the scripts block as text.
@@ -591,11 +627,30 @@ export function loadHfs(root, manifest = loadSlotManifest()) {
     validateHfs(hfs, manifest);
     return hfs;
 }
+/**
+ * The source facts as they stand once the rendered back-end source files are on disk: a managed `.ts` target of the be side counts as a
+ * file of the app (and reads as its render), so the CI shard count and the coverage scope that count or read the source name the same
+ * files before and after the targets are written, and one sync leaves the app in sync.
+ */
+export function settleSource(source, targets) {
+    const added = new Map();
+    for (const target of targets) {
+        const rel = target.scope === 'be' && target.path.startsWith('be/') ? target.path.slice('be/'.length) : '';
+        if (SOURCE_FILE.test(rel) && (rel.startsWith('apps/') || rel.startsWith('src/')) && !source.files.includes(rel))
+            added.set(rel, target.content);
+    }
+    if (added.size === 0)
+        return source;
+    return { ...source, files: [...source.files, ...added.keys()].sort(byCodeUnit), read: (file) => added.get(file) ?? source.read(file) };
+}
 /** The rendered targets of the app at `root`: its hfs.json, the Sonar key the be side's stack declaration names, the presets it installs. */
 export async function renderRepo(root, { presets, parseYaml, notices, manifest = loadSlotManifest() } = {}) {
     const hfs = loadHfs(root, manifest);
     const sonarKey = await readDeclaredSonarKey(root, { parseYaml, fail: (message) => { throw new SyncError('HFS_SYNC_SONAR_KEY', message); } });
-    return { hfs, targets: renderTargets(hfs, presets ?? await loadPresets(root), { sonarKey, manifest, source: appSource(root, { parseYaml, notices }) }) };
+    const installed = presets ?? await loadPresets(root);
+    const source = appSource(root, { parseYaml, notices });
+    const settled = settleSource(source, renderTargets(hfs, installed, { sonarKey, manifest, source }));
+    return { hfs, targets: renderTargets(hfs, installed, { sonarKey, manifest, source: settled }) };
 }
 /** The folders a lite app's sync retires (ruling lite-self-hosted-postgres-passport-minio): the generated Supabase row types nothing reads any more. */
 const LITE_RETIRED_DIRS = Object.freeze(['supabase/types']);

package/templates/app/module/jest.config.js.tpl

@@ -0,0 +1,8 @@
+/** Unit run of the {{pascal}} module package: the logic of its template and manifest is measured at 100 per file. */
+module.exports = {
+    testEnvironment: "node",
+    transform: { "^.+\.tsx?$": ["ts-jest", { tsconfig: "tsconfig.json", isolatedModules: true }] },
+    testMatch: ["<rootDir>/src/**/*.spec.ts"],
+    collectCoverageFrom: ["src/manifest/**/*.ts", "src/template/**/*.ts", "!src/**/*.spec.ts", "!src/**/index.ts"],
+    coverageThreshold: { "./src/manifest/**/*.ts": { lines: 100, branches: 100, functions: 100, statements: 100 }, "./src/template/**/*.ts": { lines: 100, branches: 100, functions: 100, statements: 100 } },
+}

package/templates/app/module/src/index.ts.tpl

@@ -0,0 +1,2 @@
+/** The key of the {{pascal}} module: its catalogue entry, its workbench and its message namespace. */
+export const {{upper}}_MODULE_KEY: "{{name}}" = "{{name}}"

package/templates/app/module/src/manifest/declaration.spec.ts.tpl

@@ -0,0 +1,11 @@
+import { {{upper}}_VIEW_IDS, {{upper}}_WORKBENCH } from "./declaration"
+
+describe("the {{pascal}} workbench declaration", () => {
+    it("declares one view per id, in strip order", () => {
+        expect({{upper}}_WORKBENCH.views.map((view) => view.id)).toEqual([...{{upper}}_VIEW_IDS])
+    })
+
+    it("is keyed like its module", () => {
+        expect({{upper}}_WORKBENCH).toMatchObject({ key: "{{name}}", namespace: "{{name}}" })
+    })
+})

package/templates/app/module/src/manifest/declaration.ts.tpl

@@ -0,0 +1,13 @@
+import type { WorkbenchDeclaration } from "@{{project}}/agent-sdk/workbench/contract"
+
+/** The views of the {{pascal}} workbench in strip order (`?tab=`), each labelled from the module's namespace. */
+export const {{upper}}_VIEW_IDS: readonly ["overview"] = ["overview"]
+
+/** The {{pascal}} workbench: one overview every member of the workspace opens; grow its views, permissions, operations and exposed reads here. */
+export const {{upper}}_WORKBENCH: WorkbenchDeclaration = {
+    key: "{{name}}",
+    namespace: "{{name}}",
+    views: [{ id: "overview", labelKey: "tab_overview" }],
+    permissions: [],
+    operations: [],
+}

package/templates/app/module/src/manifest/index.ts.tpl

@@ -0,0 +1 @@
+export { {{upper}}_VIEW_IDS, {{upper}}_WORKBENCH } from "./declaration"

package/templates/app/module/src/public/index.ts.tpl

@@ -0,0 +1,2 @@
+/** The public face of the {{pascal}} module for a front end: what a page may import without the workbench. */
+export { {{upper}}_MODULE_KEY } from "../index"

package/templates/app/module/src/template/__name__.template.spec.ts.tpl

@@ -0,0 +1,13 @@
+import { moduleListProblems } from "@{{project}}/agent-sdk/module"
+import { {{upper}}_SERVER, {{upper}}_TEMPLATE } from "./{{name}}.template"
+
+describe("{{upper}}_SERVER", () => {
+    it("is a module list the host may load", () => {
+        expect(moduleListProblems([{{upper}}_SERVER])).toEqual([])
+    })
+
+    it("serves its template under the key of the module", () => {
+        expect({{upper}}_SERVER.key).toBe({{upper}}_TEMPLATE.key)
+        expect({{upper}}_TEMPLATE).toMatchObject({ key: "{{name}}", workbench: "{{name}}" })
+    })
+})

package/templates/app/module/src/template/__name__.template.ts.tpl

@@ -0,0 +1,41 @@
+import type { ModuleServer, ModuleTemplate } from "@{{project}}/agent-sdk/module"
+
+/** The {{pascal}} module's template: its copy, agent, setup gates, authority actions and accepted commands. */
+export const {{upper}}_TEMPLATE: ModuleTemplate = {
+    key: "{{name}}",
+    order: 100,
+    name: { vi: "{{pascal}}", en: "{{pascal}}" },
+    shortName: { vi: "{{pascal}}", en: "{{pascal}}" },
+    description: { vi: "{{pascal}}", en: "{{pascal}}" },
+    points: { vi: [], en: [] },
+    purpose: "{{pascal}}",
+    icon: "module",
+    glyph: "M12 3l9 5v8l-9 5-9-5V8z",
+    mascot: "",
+    category: "operations",
+    status: "early",
+    audience: "customer",
+    includedWithWorkspace: false,
+    available: false,
+    knowledgeFolder: "{{name}}",
+    workbench: "{{name}}",
+    settingsExtras: null,
+    requires: { capabilities: [], connections: [] },
+    connectionProviders: [],
+    defaultOperatingMode: "assist",
+    multiInstance: false,
+    agent: {
+        label: { vi: "{{pascal}}", en: "{{pascal}}" },
+        handle: "{{name}}",
+        summary: { vi: "{{pascal}}", en: "{{pascal}}" },
+        capabilities: { vi: [], en: [] },
+        role: { vi: "{{pascal}}", en: "{{pascal}}" },
+        instructions: { vi: "{{pascal}}", en: "{{pascal}}" },
+    },
+    gates: [],
+    authorityActions: [],
+    accepts: [],
+}
+
+/** The server half of the {{pascal}} module: its template and the words it adds to a graph. */
+export const {{upper}}_SERVER: ModuleServer = { key: "{{name}}", template: {{upper}}_TEMPLATE }

package/templates/app/module/src/template/index.ts.tpl

@@ -0,0 +1 @@
+export { {{upper}}_SERVER, {{upper}}_TEMPLATE } from "./{{name}}.template"

package/templates/app/module/src/workbench/components/__pascal__WorkbenchView.tsx.tpl

@@ -0,0 +1,16 @@
+import type { ReactNode } from "react"
+import { EmptyNotice, Page } from "@starci/grammar/common"
+
+/** What the {{pascal}} workbench draws: its title and the words of its empty state. */
+export interface {{pascal}}WorkbenchViewProps {
+    readonly title: string
+    readonly emptyTitle: string
+    readonly emptyBody: string
+}
+
+/** Draws the {{pascal}} workbench with Grammar alone; it owns no class string, colour or visual of its own. */
+export const {{pascal}}WorkbenchView = (props: {{pascal}}WorkbenchViewProps): ReactNode => (
+    <Page header={{ title: props.title }}>
+        <EmptyNotice message={props.emptyTitle} description={props.emptyBody} />
+    </Page>
+)

package/templates/app/module/src/workbench/index.ts.tpl

@@ -0,0 +1,2 @@
+export { {{pascal}}WorkbenchView } from "./components/{{pascal}}WorkbenchView"
+export type { {{pascal}}WorkbenchViewProps } from "./components/{{pascal}}WorkbenchView"

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",
+    "test": "cd be && jest --selectProjects unit --coverage{{moduleTests}}",
     "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",
+    "test": "cd be && jest --selectProjects unit --coverage{{moduleTests}}",
     "test:integration": "npm run typecheck:tests && cd be && jest --selectProjects integration",
 {{> app/package-scripts/db.json}}
 {{backingScripts}}