@starci/hfs 5.3.0 → 5.5.0

package/sync/index.mjs

@@ -21,7 +21,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { braceVariants } from '../runtime/scripts/lib/glob.mjs';
-import { codecovPaths, coverageComponents, jestCoverage, sonarCoverageExclusions } from '../runtime/scripts/hfs/coverage-scope.mjs';
+import { codecovPaths, coverageComponents, jestCoverage, packagesCoverage, sonarCoverageExclusions } from '../runtime/scripts/hfs/coverage-scope.mjs';
 import { APP_SCOPE, SIDES, litePresenceOf, loadSlotManifest, resolveAppDeclaration, slotInEdition } from '../runtime/scripts/hfs/slots.mjs';
 import { managedGroupOf } from '../runtime/scripts/hfs/edition-slots.mjs';
 import { declaredSlotEnabled } from '../runtime/scripts/hfs/declaration-slots.mjs';
@@ -29,12 +29,14 @@ 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';
 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 { canonImport, canonList } from './canon-layout.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';
@@ -99,7 +101,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) {
@@ -248,16 +250,23 @@ 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. */
+/**
+ * The packages of `packages/` that are neither a module package nor the registry: a folder that holds a `package.json` and a `src/` (an install folder
+ * the workspaces leave there, `packages/node_modules`, is none).
+ */
 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);
+            .filter(entry => entry.isDirectory() && !entry.name.startsWith(MODULE_PREFIX) && entry.name !== 'modules'
+            && isFile(path.join(root, 'packages', entry.name, 'package.json'), { followLinks: false }) && fs.existsSync(path.join(root, 'packages', entry.name, 'src')))
+            .map(entry => entry.name).sort(byCodeUnit);
     }
     catch {
         return [];
     }
 }
+/** The app-relative folders of the root packages whose logic the back end's unit run measures: every module package and every other package, never the registry. */
+export const rootPackageFolders = (source) => [...(source?.modules ?? []).map(name => `packages/${MODULE_PREFIX}${name}`), ...(source?.otherPackages ?? []).map(name => `packages/${name}`)];
 export function appSource(root, { parseYaml, notices } = {}) {
     const files = [];
     const walk = (dir) => {
@@ -282,7 +291,7 @@ export function appSource(root, { parseYaml, notices } = {}) {
         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 }),
+        workPresent: fs.existsSync(path.join(root, '.starciwork')), hasContracts: fs.existsSync(path.join(root, 'be', 'contracts')), hasImage: (file) => isFile(path.join(root, file), { followLinks: false }),
         stack: readDeclaredStack(root, { parseYaml }), quality: readDeclaredQuality(root, { parseYaml }),
         badges: readDeclaredBadges(root, { parseYaml, notices }),
         qualityDeclared: hasDeclaredServices(root, { parseYaml }) };
@@ -336,7 +345,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-*')] : []),
+        ...(rootPackageFolders(source).length ? [line('build:modules', 'turbo run build --filter=./packages/*')] : []),
         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    ');
@@ -376,11 +385,13 @@ const IMAGE_TEMPLATE = Object.freeze({ api: 'be/image/api', worker: 'be/image/wo
 /**
  * The Dockerfile of every declared app, [{ path, content }] (app-relative): written once by starci app scaffold from templates/<side>/image/<kind>
  * and then the app's own, judged by the docker rules (R187-R191). A Next image copies the fe packages only when the fe side opts into
- * them and the be contracts only when the fe side reads them, so each COPY names a folder the app has.
+ * them and the be contracts only when the fe side reads them and the back end holds them (`source.hasContracts`: a back end that emits no
+ * contract has no be/contracts/, and a COPY of a missing folder fails the image build), so each COPY names a folder the app has.
  */
 export function imageFiles(app, source) {
     const side = app.sides.fe;
-    const inputs = [...(opensPackages(side) ? ['fe/packages'] : []), ...((side.reads ?? []).includes('be/contracts/') ? ['be/contracts'] : [])];
+    const contracts = (side.reads ?? []).includes('be/contracts/') && source?.hasContracts === true;
+    const inputs = [...(opensPackages(side) ? ['fe/packages'] : []), ...(contracts ? ['be/contracts'] : [])];
     const copyInputs = inputs.map(folder => `COPY ${folder} ${folder}\n`).join('');
     // The folders outside be/ that the back end declares it reads (the generated database types of a lite back end, db/types/) are in every one of its images.
     const beFolders = (app.sides.be.reads ?? []).map(folder => folder.replace(/\/$/, ''));
@@ -393,32 +404,49 @@ 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). */
+/**
+ * The `packages` option of the managed be/jest.config.js (`starciJestConfig`), laid out as prettier lays it out (width 120, indent 4): the root packages whose
+ * specs the unit run holds, with the files measured in them; an app without one has no such option.
+ */
+export function jestPackagesSource(packages) {
+    if (packages.folders.length === 0)
+        return '';
+    const list = (key, items) => {
+        const one = `        ${key}: [${items.map(item => JSON.stringify(item)).join(', ')}],`;
+        return one.length <= 120 ? one : [`        ${key}: [`, ...items.map(item => `            ${JSON.stringify(item)},`), '        ],'].join('\n');
+    };
+    return ['', '    packages: {', list('folders', packages.folders), list('files', packages.files), list('excludes', packages.excludes), '    },'].join('\n');
+}
+/**
+ * The managed files of the registry package for the module packages the app has (empty when it has none). An app that keeps its modules as data
+ * (hfs.json `modules: "data"`) has no rendered registry: a module is a seed there, and packages/modules, if any, is the app's own.
+ */
 function registryTargets(app, source) {
+    if (app.modules === 'data')
+        return [];
     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
+ * The root `eslint.config.mjs` of an app that has root workspace packages (packages/<name>: the agent SDK, a block library, a module package, 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`.
+ * It is laid out as the canon Prettier config prints it (`canonList`, `canonImport`), so the app's format check passes it as rendered.
  */
 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 family = grammar.package ? { name: grammar.package, factory: 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}"`] : []),
+        ...(family ? [canonImport({ names: [family.factory], from: family.name })] : []),
         '',
         '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 })` : ''}]`,
+        canonList({ head: 'export default ', items: ['...(await starciBePackagesConfig({ hfs: be }))', '...starciFePackagesConfig({ hfs: fe })', ...(family ? [`...${family.factory}({ hfs: fe })`] : [])] }),
         '',
     ].join(LINE);
     return [{ path: PACKAGES_LINT_FILE, scope: APP_SCOPE, mode: 'file', content, hash: hashOf(content) }];
@@ -430,10 +458,11 @@ 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 && ' : '';
+    // The root packages (the agent SDK, the module packages and the rest) are built before anything imports them (typecheck, lint, the fe build and the be
+    // run), and their logic is measured by the back end's unit run like its own (packagesCoverage, BE-TEST-13).
+    const rootPackages = packagesCoverage(rootPackageFolders(source));
+    const moduleDirs = rootPackages.folders;
+    const modulesFirst = moduleDirs.length ? 'npm run build:modules --silent && ' : '';
     const grammarLint = scope === 'fe' ? grammarLintFor(fe.grammar) : null;
     return {
         header: HEADER(scope),
@@ -456,9 +485,8 @@ 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 && '}`,
-        // 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.
+        // The unit run, the back-end build and every CI job that imports a root package find it built (build:modules precedes them); its specs run in the unit run and its shards.
         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,
@@ -471,12 +499,13 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
         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 }),
+        ...ciWorkflowCommands(source, LCOV_REPORT, source.qualityDeclared === false ? undefined : source.quality, { app, packages, rootPackages: moduleDirs.length > 0 }),
         // 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), ...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') : '',
+        jestPackages: scope === 'be' ? jestPackagesSource(rootPackages) : '',
+        coverageExclusions: scope === APP_SCOPE ? [...sonarCoverageExclusions(manifest, providers), ...rootPackages.excludes].join(',') : '',
+        codecovExclusions: scope === APP_SCOPE ? [...sonarCoverageExclusions(manifest, providers), ...rootPackages.excludes].map(glob => `  - ${JSON.stringify(glob)}`).join('\n') : '',
+        codecovPaths: scope === APP_SCOPE ? [...codecovPaths(manifest, providers), ...moduleDirs.map(dir => `${dir}/src/**`)].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),
@@ -548,7 +577,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 }) };
             })];
     });
 }
@@ -714,6 +743,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');
@@ -738,7 +777,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>]');
@@ -754,18 +793,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/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' }}
@@ -101,7 +101,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        side: [be, fe]
+        side: {{lintSides}}
     steps:
 {{> app/ci-workflows/install-steps.yml}}
 {{> app/ci-workflows/lint-base.yml}}

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' }}
@@ -101,7 +101,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        side: [be, fe]
+        side: {{lintSides}}
     steps:
 {{> app/ci-workflows/install-steps.yml}}
 {{> app/ci-workflows/lint-base.yml}}

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

@@ -40,6 +40,32 @@ environments:
     runbook: README.md
     # Custody starts empty; add real sealed members after owner provisioning.
     secrets: []
+    # `starci app stack up --env dev --execute` reads this block (PROJECT-STACKS-6): the compose services in dependency order, each
+    # awaited on its healthcheck, then readiness and the origins. The app images come from `starci app stack prepare --env dev --execute`.
+    local:
+      ports:
+        core: 3001
+        app: 3000
+        landing: 3002
+      services:
+        - {name: postgres, wait: healthy}
+        - {name: core, wait: healthy, port: core}
+        - {name: app, wait: healthy, port: app}
+        - {name: landing, wait: healthy, port: landing}
+      ready:
+        - {name: core-live, url: "http://127.0.0.1:${port.core}/health/live"}
+        - {name: core-ready, url: "http://127.0.0.1:${port.core}/health/ready"}
+        - {name: app-live, url: "http://127.0.0.1:${port.app}/health/live"}
+        - {name: landing-live, url: "http://127.0.0.1:${port.landing}/health/live"}
+      verify:
+        - {name: core-live, url: "http://127.0.0.1:${port.core}/health/live"}
+        - {name: core-ready, url: "http://127.0.0.1:${port.core}/health/ready"}
+        - {name: app-live, url: "http://127.0.0.1:${port.app}/health/live"}
+        - {name: landing-live, url: "http://127.0.0.1:${port.landing}/health/live"}
+      origins:
+        - {name: app, url: "http://127.0.0.1:${port.app}"}
+        - {name: landing, url: "http://127.0.0.1:${port.landing}"}
+        - {name: core, url: "http://127.0.0.1:${port.core}"}
   production:
     status: supported
     runtime: docker-swarm

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

@@ -1,16 +1,27 @@
 # Development stack
 
-Every development dependency runs in Docker Linux containers. This starter's Docker Compose model contains the core API, the product and landing front ends, and a pinned local PostgreSQL database. Compose is an implementation detail; declared dependencies may also use managed `<dep>:create`, `<dep>:start` and `<dep>:stop` scripts. A declared native profile may run app processes locally while dependencies stay in Docker. Trust authentication is confined to this local, unpublished database.
-Starter release images and external secrets must be prepared before starting the container model. Local source development remains available through the app scripts.
+The dev environment is one command: `starci app stack up --env dev --execute`. It checks the machine, opens the dev custody, starts the
+compose services of `infra/compose/stack.yaml` in Docker Linux containers (the pinned local PostgreSQL first, then the core API and the product
+and landing front ends), waits for each healthcheck and for readiness, and prints the origins. 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. Trust authentication is confined to this local, unpublished database.
+
+**A new machine.** Install what `starci app stack doctor --env dev` reports missing (it prints the exact winget, brew or apt step per tool; Node
+from `.nvmrc`, npm, git, Docker with Compose v2 running Linux containers, WSL2 on Windows, sops and age), then run `prepare` and `up`.
+
+**Custody.** The API reads its database connection from the owner-controlled file `/run/starci-secrets/{{project}}/dev/primary-db-url`, which
+the compose model mounts into the API; materialize its real sealed member there before `up`. The scaffold creates no fake secret or
+successful proof.
 
 | Command | Operation |
 | --- | --- |
-| prepare | Build the app images and provide the local database connection through sealed custody. Materialize its real sealed member to the owner-controlled file `/run/starci-secrets/{{project}}/dev/primary-db-url`; Docker Compose mounts that file into the API. |
-| doctor | From this directory, run `docker compose config -f infra/compose/stack.yaml`. Confirm image, secret and database availability. |
-| up | Run `docker compose -f infra/compose/stack.yaml up -d` from this directory after preparation. |
-| status | Run `docker compose -f infra/compose/stack.yaml ps`. |
-| logs | Run `docker compose -f infra/compose/stack.yaml logs core`; never print mounted credentials. |
-| down | Run `docker compose -f infra/compose/stack.yaml down`. |
-| verification | Confirm the API `/health/live` and `/health/ready` endpoints, then run `npm run lint` from the app root. |
+| prepare | `starci app stack prepare --env dev --execute`: checks the machine, opens the custody and builds the app images. |
+| doctor | `starci app stack doctor --env dev`: read-only table of host prerequisites with the owner-run install step per OS, custody, compose render and ports. |
+| up | `starci app stack up --env dev --execute`: prepare, then the services in order and readiness; prints the origins. |
+| status | `starci app stack status --env dev`: desired against running and every readiness probe. |
+| logs | `starci app stack logs --env dev --service core` (a compose service, bounded and redacted; never prints mounted credentials). |
+| down | `starci app stack down --env dev --execute`: 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. |
 
-Keep real sealed members under `.starcistacks/dev/secrets/*.enc`, add them to the manifest after sealing and inventory their key names in the environment record. The scaffold creates no fake secret or successful proof.
+Keep real sealed members under `.starcistacks/dev/secrets/*.enc.yaml`, add them to the manifest after sealing and inventory their key names in
+`.starcistacks/dev/runtime/env/KEYS.md`.

package/templates/app/skeleton/.starcistacks/dev/seeds/seeds.yaml

@@ -0,0 +1,3 @@
+schema: starci/seeds@1
+entries:
+  - {id: primary-notes, kind: sql, path: sql/primary-notes.sql, target: primary, mode: upsert}

package/templates/app/skeleton/.starcistacks/production/seeds/seeds.yaml

@@ -0,0 +1,2 @@
+schema: starci/seeds@1
+entries: []

package/templates/app/skeleton/.starcistacks/seeds/seeds.yaml

@@ -0,0 +1,2 @@
+schema: starci/seeds@1
+entries: []

package/templates/app/skeleton/README.md

@@ -36,7 +36,7 @@ npm run build:fe
 The core api app reads `PORT`, `HTTP_SECURITY_ALLOWED_ORIGINS` (comma-separated origins allowed to send state-changing browser
 requests) and `PRIMARY_DB_URL` at boot; every door is closed until it is marked public or sign-in is designed. The cli app reads
 `PRIMARY_DB_URL`: `npm run migrate` applies the migrations of the primary database before the api starts, and
-`npm run cli -- seed run` runs the dev seeds of `.starcistacks/dev/seeds` (run both from the app root). The product app reads
+`npm run cli -- seed run` runs the SQL seeds of `.starcistacks/seeds/sql/`, then those of `.starcistacks/dev/seeds/sql/` (`--env <env>` names another environment; run both from the app root). The product app reads
 `NEXT_PUBLIC_SITE_URL` and `NEXT_PUBLIC_GRAPHQL_URL` (the back end it calls through `fe/apps/app/src/modules/api`, read once the first GraphQL operation exists), the landing `NEXT_PUBLIC_APP_URL` (the product app it hands the reader over to). A missing key stops the process with an error that names it.
 
 Production browser build values live in `.starcistacks/application-stacks.yaml` under `environments.production.deploy.images.*.buildArgs.values`. Replace the placeholder origins for the product's `NEXT_PUBLIC_SITE_URL` and the landing's `NEXT_PUBLIC_APP_URL` with your product app's public origin before building deployment images.

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`; the `mail` service: Mailpit, the dev mail sink), 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, applies the seed levels `.starcistacks/seeds/` then `.starcistacks/dev/seeds/`, 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.
 
@@ -20,7 +20,7 @@ another environment.
 | --- | --- |
 | prepare | `starci app stack prepare --env dev --execute`: checks the machine, opens the custody, runs the setup commands and builds the images. |
 | doctor | `starci app stack doctor --env dev`: read-only table of host prerequisites with the owner-run install step per OS, custody, compose render and ports. |
-| up | `starci app stack up --env dev --execute`: prepare, then the services, the database role, migrations with a receipt, the seed, the processes and readiness; prints the origins. |
+| up | `starci app stack up --env dev --execute`: prepare, then the services, the database role, migrations with a receipt, the seed levels `.starcistacks/seeds/` then `.starcistacks/dev/seeds/`, each entry once per content hash, the processes and readiness; prints the origins. |
 | status | `starci app stack status --env dev`: desired against running, the migration receipt and every readiness probe. |
 | logs | `starci app stack logs --env dev --service api` (a process or a compose service, bounded and redacted). |
 | down | `starci app stack down --env dev --execute`: ends the processes and stops the compose project; volumes and sealed values stay. |

package/templates/app/skeleton-lite/.starcistacks/dev/seeds/seeds.yaml

@@ -0,0 +1,2 @@
+schema: starci/seeds@1
+entries: []

package/templates/app/skeleton-lite/.starcistacks/production/seeds/seeds.yaml

@@ -0,0 +1,2 @@
+schema: starci/seeds@1
+entries: []

package/templates/app/skeleton-lite/.starcistacks/seeds/seeds.yaml

@@ -0,0 +1,2 @@
+schema: starci/seeds@1
+entries: []

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

@@ -12,10 +12,10 @@ TypeScript everywhere, NestJS in `be/`, Next.js with next-intl in `fe/`, Postgre
 
 ## Repository layout
 
-- `db/`: forward-only SQL migrations, seed data, and generated database types.
+- `db/`: forward-only SQL migrations and generated database types.
 - `be/`: the API, shared platform capabilities, verified identity admission, and the passport and storage integrations.
 - `fe/`: the web app; it holds no credential, signs in through `fe/apps/web/src/modules/auth` and reaches data through `fe/apps/web/src/modules/api`.
-- `.starcistacks/`: value-free environment metadata and encrypted-secret custody.
+- `.starcistacks/`: value-free environment metadata, encrypted-secret custody and the seed levels (`seeds/` for every environment, `<env>/seeds/` for one, each a `seeds.yaml` manifest of `sql/`, `data/` and `files/`).
 - `.starciwork/`: `.gitignore`, `.starciwork/workspace.yaml` project metadata and repo roles, and optional brand drawing records, references, and assets.
 
 ## Status badges

package/templates/app/skeleton-lite/db/migrations/__timestamp___baseline.sql

@@ -25,7 +25,8 @@ end;
 $$;
 
 -- The device sessions and rotating refresh tokens of @starci/auth. A token is stored by its sha256 only; a rotated token stays,
--- marked used, so a replay is detected (a replay inside the grace window is a racing tab, an older one ends the session).
+-- marked used, so a replay is detected: a replay inside the grace window gets a successor of its own (raced_count bounds how many),
+-- an older one ends the session and every token of it.
 -- identity_attempts counts the sign-in attempts of one address in a window every replica shares (the budget of failures).
 -- The app owns auth.users (db/bootstrap.sql) and the role app_be.
 
@@ -48,6 +49,7 @@ create table public.identity_refresh_tokens (
     created_at timestamptz not null default now(),
     expires_at timestamptz not null,
     used_at timestamptz,
+    raced_count integer not null default 0,
     constraint identity_refresh_tokens_hash_key unique (token_hash)
 );
 

package/templates/be/auth-lite/src/features/api/auth/application/auth.contracts.ts

@@ -17,6 +17,8 @@ export interface SignupData {
     readonly email: string
     /** The chosen password. */
     readonly password: string
+    /** The person's full name, when the request names one. */
+    readonly name: string | undefined
     /** The language of the confirmation mail, when the request names one. */
     readonly language: MailLanguage | undefined
 }

package/templates/be/auth-lite/src/features/api/auth/application/signup.handler.ts

@@ -17,6 +17,11 @@ export class SignupHandler extends ICQRSHandler<SignupCommand, void> {
     }
 
     protected override process(command: SignupCommand): Promise<void> {
-        return this.email.signup(command.params.request.email, command.params.request.password, command.params.request.language)
+        return this.email.signup(
+            command.params.request.email,
+            command.params.request.password,
+            command.params.request.language,
+            command.params.request.name,
+        )
     }
 }

package/templates/be/auth-lite/src/features/api/auth/auth.module.ts

@@ -15,7 +15,20 @@ import { ResetHandler } from "./application/reset.handler"
 import { ConfigurableModuleClass } from "./auth.module-definition"
 
 @Module({
-    providers: [LoginHandler, RefreshHandler, SessionHandler, LogoutHandler, GoogleBeginHandler, GoogleCompleteHandler, GetJwksHandler, SignupHandler, ResendHandler, ConfirmHandler, ForgotHandler, ResetHandler],
+    providers: [
+        LoginHandler,
+        RefreshHandler,
+        SessionHandler,
+        LogoutHandler,
+        GoogleBeginHandler,
+        GoogleCompleteHandler,
+        GetJwksHandler,
+        SignupHandler,
+        ResendHandler,
+        ConfirmHandler,
+        ForgotHandler,
+        ResetHandler,
+    ],
 })
 /** The auth feature: the handlers behind the sign-in doors. */
 export class AuthApiModule extends ConfigurableModuleClass {}

package/templates/be/auth-lite/src/features/api/auth/transport/http/auth.controller.ts

@@ -96,7 +96,11 @@ export class AuthController {
     @Public({ reason: PublicReason.AuthHandshake })
     @RateLimit(RateTier.Strict)
     signup(@Body() body: SignupRequest): Promise<void> {
-        return this.commandBus.execute(new SignupCommand({ request: { email: body.email, password: body.password, language: body.language } }))
+        return this.commandBus.execute(
+            new SignupCommand({
+                request: { email: body.email, password: body.password, name: body.name, language: body.language },
+            }),
+        )
     }
 
     /** Mails a new confirmation link; always answers 204. */

package/templates/be/auth-lite/src/features/api/auth/transport/http/dto/reset.request.ts

@@ -14,5 +14,4 @@ export class ResetRequest {
     @MinLength(1)
     @MaxLength(128)
     password!: string
-
 }

package/templates/be/auth-lite/src/features/api/auth/transport/http/dto/signup.request.ts

@@ -15,6 +15,13 @@ export class SignupRequest {
     @MaxLength(128)
     password!: string
 
+    /** The person's full name, kept on the account's profile keys; left out, the account has none. */
+    @IsOptional()
+    @IsString()
+    @MinLength(1)
+    @MaxLength(200)
+    name?: string
+
     /** The language of the mail; the app's default when left out. */
     @IsOptional()
     @IsIn(["vi", "en"])