@starci/hfs 5.1.0 → 5.3.0

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';
@@ -236,6 +237,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']);
 /**
@@ -244,6 +248,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 +281,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 +336,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 +393,36 @@ 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) }));
+}
+/**
+ * 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;
@@ -384,6 +430,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 +451,14 @@ 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 && '}`,
+        // 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,
@@ -415,19 +468,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 +499,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 +532,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), ...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);
+                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,17 +656,38 @@ 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']);
 /** 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. */

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/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/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",
+    "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",
+    "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}}