@starci/hfs 5.3.0 → 5.5.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 5.5.0 - 2026-11-03
+
+- Changed: the back end's unit run holds the root packages (`packages/<name>` with a `package.json` and a `src/`, never the registry): their specs run in `npm test`, `app check --gate test` and the CI shards, and their logic is measured at 100 per file (the workbench, the public face and the barrels aside) inside the Sonar and Codecov scope. `test:modules`, the fast job's module-packages step and the per-package `jest.config.js` are removed; `starci app sync` renders the change (PROJECT-3, BE-TEST-13).
+- Fixed: each lint scope runs on its own: a side whose ESLint child does not complete is a tool error of that side (exit 2), and the next side and the root packages are still judged; a host hold still ends the run. The ESLint liveness budget of a diff run scales with the files of the side, whose typed program the child builds, not with the length of the diff.
+- Added: `app check --gate lint --side packages`; an app with root packages lints them in a job of the CI lint matrix (`[be, fe, packages]`) with their own Sonar report, and the release gate's lint report does the same.
+- Added: a root workspace package declares its own error base and result union in its `package.json` (`starci.errorBase`, `starci.outcome`), read by the root-packages view (`readPackageContract`).
+- Fixed: `app sync` renders the root `eslint.config.mjs` and the module registry (`tsconfig*.json`, `src/template`, `src/manifest`) as the canon Prettier config prints them, so an app's prettier hook passes them and formatting them is no longer `HFS_SYNC_DRIFT`; the managed lite sign-in templates are Prettier output.
+- Added: hfs.json `"modules": "data"` declares that an app keeps its agent modules as data (`.starcistacks/seeds/data/modules`): `app sync` renders no registry package `packages/modules` (one the app keeps is its own code), and `app add|remove module` refuse `HFS_MODULES_ARE_DATA`. An app without the key keeps the module-packages render.
+- Added: seed levels `.starcistacks/seeds/` (every environment, first) and `.starcistacks/<env>/seeds/`, each a `seeds.yaml` (`starci/seeds@1`) with `sql/`, `data/` and `files/` and entry kinds `sql`, `data`, `test-account` and `files`, judged by R375 (`HFS_SEEDS_SHAPE`, `HFS_SEED_MANIFEST`, `HFS_SEED_DDL`, `HFS_SEED_DATA_SCHEMA`, `HFS_SEED_TEST_DATA`, `HFS_SEED_SECRET_REF`); `HFS_SEED_PII` also reads JSON and YAML seed data; a production level holds test data only in its one declared `test-account` entry. New apps are scaffolded with the three levels.
+- Added: the seed step (`stack/seeds.mts`): receipts in `public.starci_seed_receipts` (scope, id, content hash, secret member names with a digest), `once` and `upsert` entries, secret references (`{ "secret": "seeds-<name>" }`) opened in memory with the env's age identity and passed to the app's seed command on stdin, never to disk, argv, logs or receipts; `files` entries are checked only. `app stack up` runs it after the migrations, and the deploy after convergence, its dry run listing the entries (PROJECT-STACKS-6, PROJECT-STACKS-12).
+- Changed: `db baseline --squash` writes `.starcistacks/seeds/sql/reference.sql` and declares the entry `reference`; the scaffold's `cli seed run` reads the shared then the env `sql/` folder (the lite one takes `--env`); slot `app.db.seed` is removed and R332 refuses `db/seed.sql`.
+- Fixed: `app codemod sops-rules` keeps the comment header `.sops.yaml` opens with (the managed header of `secret init`).
+- Fixed: a fresh `app scaffold --edition full` passes its own check: the dev environment declares the `local` block `app stack up --env dev` runs, and its runbook names the `starci app stack` verbs instead of docker commands.
+- Fixed: the Next image of a front end that reads `be/contracts/` copies it only when the back end holds it; R187 (`HFS_DOCKER_BUILD_CONTEXT`) refuses a COPY of a missing `be/contracts` and a missing COPY once contracts exist.
+- Changed: the lite sign-up door takes an optional full name and keeps it as `full_name` and `name` in the account's profile data, and the scaffolded sign-up form asks for it; the lite account directory and the Google sign-in read it back into the session (`AccountStanding.name`, `@starci/auth` 0.3.0).
+- Changed: the canon pins carry no release-age wording (a version, security fixes included, may be adopted as soon as it is published), and name `@starci/auth` 0.3.0, `@starci/auth-oidc` 0.1.2, the Grammar family 0.21.17, `@starci/eslint-canon-be` 3.15.0, `@starci/eslint-canon-fe` 9.13.0 and `@starci/jest-preset` 2.7.0.
+- Upgrade: (1) `npx starci app codemod seeds-layout`, read the report, then `--execute`: it moves `db/seed.sql` and loose `.starcistacks/<env>/seeds/*.sql` into the seed levels and writes their manifests; move any secret out of seed data into a `seeds-<name>` member and declare production's one test account as a `test-account` entry. (2) An app that keeps its modules as data adds `"modules": "data"` to hfs.json. (3) An app whose back end emits no contract deletes `COPY be/contracts be/contracts` from its `fe/apps/*/Dockerfile`, which the app owns. (4) `npx starci app sync --execute` renders the jest packages scope, the CI lint matrix and the Prettier-clean managed files.
+- Changed: slot `app.packages` places any root workspace package `packages/<name>/` (the agent SDK, a block library such as `packages/blocks-core`, a module package, later a reviewed plugin package), not only `agent-sdk` and `module-<name>`, so each is linted by the root config (`--side packages`) and read as a first-party package by the import graph; slot manifest 3.19.0 (ruling `root-packages-any-name`).
+
+## 5.4.0 - 2026-11-03
+
+- Fixed: `starci app sync --execute` never leaves an app uncompilable. Before it writes a managed TypeScript file or deletes a retired one, it compiles each front-end and back-end project with the change applied (the app's own TypeScript; the changed files and every file importing them, against what is on disk). A managed group whose render adds a type error, in its own files or in an app file that imports one, is held whole: `HFS_SYNC_GROUP_HELD`, exit 1, naming the group, its files and the first errors (what the app must add or still imports); the rest is written, and a side without TypeScript installed is named in a notice (`sync/compile-guard.mts`).
+- Fixed: `starci app codemod module-definition` drops every imported name the rewrite made unused (`ConfigurableModuleCls`, `ConfigurableModuleHost`, `ConfigurableModuleBuilder`), keeps the names the file still uses and `import type`, keeps the builder's JSDoc, and writes each file as the app's Prettier prints it, so no TS6133 and no prettier-hook refusal follow it (`codemod/app-prettier.mts`).
+- Changed: `starci app codemod account-doors --contract` says why it writes nothing: the contract migration is already in the chain, or no migration grants the app role on schema `auth`.
+- Changed: the lite sign-in renders `@starci/auth` 0.2.1: `identity_refresh_tokens.raced_count` in the baseline (the package's `identity-sessions.sql`), the refresh-token entity's `racedCount` and the session store's `markTokenRaced`. An app whose baseline holds the 0.2.0 tables adds `@starci/auth/migrations/identity-refresh-raced-successors.sql` as a migration.
+- Changed: the canon pins name `@starci/auth` 0.2.1, `@starci/auth-oidc` 0.1.1 and the Grammar family 0.21.16.
+- Upgrade, for an app on the CLI 1.1.0-alpha.49 / hfs 5.0.8 render moving to this version: (1) `npx starci app codemod module-definition --execute`, then `npm install`; (2) `npx starci app sync --execute`, which writes everything that compiles and holds the auth-lite sign-in glue while the app's own identity code differs, naming each missing or still-imported symbol; (3) adopt `@starci/mail` and make the identity domain provide what the held errors name; (4) `npx starci app sync --execute` again, which writes the glue once it compiles; (5) `npx starci app codemod account-doors --execute`, and `--contract` when the app still grants on schema `auth`; (6) add the `raced_count` migration above.
+
 ## 5.3.0 - 2026-11-03
 
 - Fixed: the secrets family of the committed check cache stores codes, paths, positions and digests only (`cache/secret-records.mts`, `runtime/scripts/lib/secret-records.mts`), and the one secret judgement of R06 judges a file of `.starcistacks/cache/check/secrets/` by that contract, so `starci app check` can no longer write a cache the staged guard refuses (`HFS_PLAINTEXT_SECRET` for the `secrets/` folder name). A cache written before reads back as digests. Codemod: `starci app codemod secrets-cache`.

package/README.md

@@ -33,8 +33,9 @@ starci app ci secret set <NAME> [--from-custody] [--env <env>] [--repo <owner/na
 `.starcistacks/application-stacks.yaml` (PROJECT-STACKS-6 of `contexts/project/stacks.md`): the host table (`doctor` prints the owner-run install
 step per OS for each missing prerequisite and installs nothing), the dev custody (`secret init --env dev --execute` creates the dev-only values once),
 the setup commands, the compose services and their health, the environment's own database role, the migrations with a receipt (`db migrate` runs its
-client tools in the database container named by `STARCI_DB_CONTAINER`, so the host needs no PostgreSQL client), the seed once, the native app
-processes, readiness and the origins. `prepare`, `up` and `down` are dry runs until `--execute`; `down` never removes a volume. State (process ids,
+client tools in the database container named by `STARCI_DB_CONTAINER`, so the host needs no PostgreSQL client), the seed levels of `.starcistacks/`
+with their receipts in the database (`stack/seeds.mts`, PROJECT-STACKS-12; `app codemod seeds-layout` moves an older app's seed data into them),
+the declared seed commands once, the native app processes, readiness and the origins. `prepare`, `up` and `down` are dry runs until `--execute`; `down` never removes a volume. State (process ids,
 logs, receipts) is under the state base (`STARCI_LOCAL_ROOT`), the opened custody under the private secrets directory outside the checkout.
 
 `starci app add` writes every front-end unit, in either edition, already in the shape of the harness's `contexts/code/fe`
@@ -114,7 +115,7 @@ one is refused with both names. Object references and function bodies stay byte-
 the kept pgmq queues and the grants on objects outside the app schemas), a marked section of `db/bootstrap.sql` (the source's app roles
 with their attributes and no password, their memberships, their allowed role settings such as `search_path`, the grants on schemas the
 bootstrap creates and the database-wide default privileges, none of which a per-database dump keeps; `starci app sync` judges and keeps
-the rest of the file), `db/seed.sql` (the rows of `--seed-tables`, `insert ... on conflict do nothing` in foreign-key order with their
+the rest of the file), `.starcistacks/seeds/sql/reference.sql` (the rows of `--seed-tables`, declared as the entry `reference` of the shared seed level, `insert ... on conflict do nothing` in foreign-key order with their
 sequences set; a table without a primary key or unique constraint is refused) and moves the chain to `db/migrations/archive/`. Before
 writing, a scratch container of the app's db image (built from `.starcistacks/images/db/Dockerfile`, or `--image`) replays bootstrap, baseline and seed (the
 seed twice); the same projection read from the replay must equal the source's, or the verb refuses with the differences. Docker runs every
@@ -207,6 +208,7 @@ Its own checks (`scripts/hfs/check.mjs`, `scripts/hfs/rules/`; the rendered-file
 
 The managed files are judged by `sync/managed.mjs` and `sync/ts-strict.mjs` (the package renders the templates; the runtime copy does not). The list of managed
 files is the `managedBy` slots of `slots.yaml`; `starci app sync --execute` renders them and `starci app check` compares them, so a hand edit and a forgotten `sync` are the same finding.
+`starci app sync --execute` never leaves the app uncompilable (`sync/compile-guard.mjs`): before it writes a managed TypeScript source or deletes a retired one, the side's own TypeScript compiles the app with those writes over the disk, and a managed group (`managedBy`) whose writes add a type error, in its own files or in an app file that imports one, is held whole: `HFS_SYNC_GROUP_HELD` (exit 1) names the group, its files and the errors (the names the render reads that the app does not provide yet, or the names it drops that the app still imports), and the rest of the render is written. The held files stay `HFS_SYNC_DRIFT` until the app provides what the render reads and sync runs again; a side whose TypeScript is not installed is written and named in a notice.
 Each finding is reported once: the managed ESLint and stylelint factory configs under R17, `tsconfig.json` under R22 when it names a flag, a workflow or hook that lost a canon step under R13 (or R19 for the format step), everything else under R05.
 The root and both sides are rendered by the one mechanism. The root: the `scripts` block of `app.package-manifest` (`dev:be`, `dev:fe`, `build:be`, `build:fe`, `start:<app>`, `lint`, `lint:fix`, `test`, `test:integration`, `test:e2e`, `test:contract`, `test:world`, `codegen`, `contract:emit`, `migrate`, `typecheck`, ...; a be script runs from `be/`, where its tsconfig and jest configuration are), `app.format-config`, `app.hooks`, the CI slots (`app.ci`, `app.ci-e2e`, `app.ci-images`), `app.quality-config` and the managed block of `app.git-meta`. A side: its `be.tool-config` or `fe.tool-config` slot — the side's tsconfig (resolving `@starci/tsconfig` from the root `node_modules`) and its managed ESLint factory config, the back end's build tsconfig, tests tsconfig and jest configuration, the front end's stylelint configuration. `lint` is `starci app check --gate lint`: ESLint over each side with its canon and stylelint over fe; `lint:fix` is the same with `--fix`. The front end has no test script, no test configuration and no e2e or coverage file: it has no tests, and `FE_NO_TESTS` (R97) refuses any spec, e2e file, test tool or test script under `fe/`. `turbo.json` stays the app's own
 (slot `app.task-graph`): it carries the task graph, which no preset can render.

package/cache/test-family.d.mts

@@ -96,7 +96,7 @@ export declare function sourcesOf(record: CacheRecord): Record<string, SourceIte
  * a failing one's is not, and the folder is replaced with exactly the current specs' records. The merged total is written to `<side>/coverage/lcov.info` and judged.
  */
 export declare function runTestFamily(options: TestFamilyOptions): Promise<TestFamilyResult>;
-/** The part of a Jest project config the closure needs. */
+/** The part of a Jest project config the closure needs. A project's `roots` are where its haste map finds its files. */
 interface ProjectConfigLike {
     readonly rootDir: string;
     readonly displayName?: {

package/cache/test-family.mjs

@@ -49,8 +49,9 @@ export function sourcesOf(record) {
 }
 function recordOf(spec, key, sources, side) {
     const prefixed = {};
+    // A source is relative to the Jest root; a root package's (`../packages/<name>/...`) is outside it, so the joined path is normalised to the app root.
     for (const [source, items] of Object.entries(sources))
-        prefixed[side === '' || side === '.' ? source : `${side}/${source}`] = items;
+        prefixed[side === '' || side === '.' ? source : path.posix.normalize(`${side}/${source}`)] = items;
     return { path: spec, step: SPEC_STEP, hash: key, findings: [], data: { sources: prefixed } };
 }
 /**
@@ -163,24 +164,27 @@ export async function createJestEnvironment({ appRoot, side, jestFrom, project =
     const Runtime = runtimeModule.default;
     const { DependencyResolver } = fromCore('jest-resolve-dependencies');
     const jestBin = path.join(path.dirname(jestPackage), 'bin', 'jest.js');
-    // The preset's config reads the working directory (the back end it describes), so it is read from the Jest root.
+    // The preset's config reads the working directory (the back end it describes), so it is read from the Jest root. Several projects may carry the name
+    // (the back end's unit project and the one of the app's root packages, rooted at the app root): each keeps its own haste map and resolver.
     const previous = process.cwd();
-    let config;
-    let context;
+    const projects = [];
     try {
         process.chdir(root);
         const { configs } = await readConfigs({ $0: 'jest', _: [], selectProjects: [project] }, [root]);
-        config = configs.find((entry) => entry.displayName?.name === project);
-        if (config === undefined)
+        for (const config of configs.filter((entry) => entry.displayName?.name === project)) {
+            const context = await Runtime.createContext(config, { maxWorkers: 1, watchman: false, console: { log: () => undefined, warn: () => undefined, error: () => undefined } });
+            projects.push({ config, resolver: new DependencyResolver(context.resolver, context.hasteFS, undefined), hasteFS: context.hasteFS });
+        }
+        if (projects.length === 0)
             throw new Error(`the Jest config under ${side} has no project named ${project}`);
-        context = await Runtime.createContext(config, { maxWorkers: 1, watchman: false, console: { log: () => undefined, warn: () => undefined, error: () => undefined } });
     }
     finally {
         process.chdir(previous);
     }
-    const resolver = new DependencyResolver(context.resolver, context.hasteFS, undefined);
     const tracked = (file) => !file.split(/[\\/]/u).includes('node_modules');
-    const closureFrom = (roots) => {
+    /** The project whose haste map holds `file`: a module is resolved the way the project that runs its spec resolves it. */
+    const projectOf = (file) => projects.find((entry) => entry.hasteFS.exists(file)) ?? projects[0];
+    const closureFrom = (roots, owner) => {
         const seen = new Set();
         const queue = roots.filter(tracked);
         while (queue.length > 0) {
@@ -188,15 +192,14 @@ export async function createJestEnvironment({ appRoot, side, jestFrom, project =
             if (file === undefined || seen.has(file))
                 continue;
             seen.add(file);
-            for (const next of resolver.resolve(file))
+            for (const next of owner.resolver.resolve(file))
                 if (tracked(next) && !seen.has(next))
                     queue.push(next);
         }
         return [...seen];
     };
     const relative = (file) => posix(path.relative(appRoot, file));
-    const setup = (name) => [...(config[name] ?? [])];
-    const setupClosure = closureFrom([...setup('setupFiles'), ...setup('setupFilesAfterEnv')]).map(relative);
+    const setupClosures = new Map(projects.map((entry) => [entry, closureFrom([...(entry.config.setupFiles ?? []), ...(entry.config.setupFilesAfterEnv ?? [])], entry).map(relative)]));
     const listed = completedNode(await runHeavyNode(execute, { kind: 'test', label: `app check jest ${project} discovery`, args: [jestBin, '--selectProjects', project, '--listTests'], cwd: root, maxBuffer: 64 * 1024 * 1024 }), 'jest discovery');
     if (listed.status !== 0)
         throw new Error(`jest --listTests failed under ${side}: ${(listed.stderr || listed.stdout).split('\n')[0]}`);
@@ -204,13 +207,15 @@ export async function createJestEnvironment({ appRoot, side, jestFrom, project =
     const closures = new Map();
     return {
         specs,
-        configHash: projectConfigHash(config),
+        configHash: projects.length === 1 ? projectConfigHash(projects[0].config) : combineHashes(Object.fromEntries(projects.map((entry, index) => [String(index), projectConfigHash(entry.config)]))),
         closureOf(spec) {
             const cached = closures.get(spec);
             if (cached !== undefined)
                 return cached;
-            const own = closureFrom([path.resolve(appRoot, spec)]).map(relative).filter((file) => file !== spec);
-            const closure = [...new Set([...own, ...setupClosure])].sort();
+            const file = path.resolve(appRoot, spec);
+            const owner = projectOf(file);
+            const own = closureFrom([file], owner).map(relative).filter((entry) => entry !== spec);
+            const closure = [...new Set([...own, ...(setupClosures.get(owner) ?? [])])].sort();
             closures.set(spec, closure);
             return closure;
         },

package/codemod/account-doors.mjs

@@ -97,8 +97,14 @@ export function migrateAccountDoors({ root, write = false, contract = false, now
     }
     if (report.findings.length)
         return report;
-    if (names.some((name) => name.includes(`_${CONTRACT_NAME}`)) || !names.some((name) => AUTH_GRANT.test(statementsOf(root, name))))
+    if (names.some((name) => name.includes(`_${CONTRACT_NAME}`))) {
+        report.next.push('the contract migration is already in the chain: nothing is left to revoke');
         return report;
+    }
+    if (!names.some((name) => AUTH_GRANT.test(statementsOf(root, name)))) {
+        report.next.push('no migration grants the application role on schema auth (the app reached accounts through the doors from the start): nothing to revoke');
+        return report;
+    }
     const file = `${MIGRATIONS_DIR}/${stamp}_${CONTRACT_NAME}.sql`;
     report.changes.push({ file, phase, why: 'revokes the direct grants on schema auth, auth.users and auth.identities from the application role' });
     report.next.push('the deploy applies it right after the accept; the release before the doors cannot sign in after a rollback unless the grants are given back');

package/codemod/app-prettier.d.mts

@@ -0,0 +1,5 @@
+import { type Prettier } from '../sync/format.mjs';
+/** The app's own Prettier, from the first side or the root that installs one, or undefined. */
+export declare function prettierOf(root: string, folders: readonly string[]): Prettier | undefined;
+/** `text` formatted by the app's Prettier the way `app check --format` judges it, or unchanged when the file is ignored or cannot be formatted. */
+export declare function formatted(prettier: Prettier, root: string, file: string, text: string): Promise<string>;

package/codemod/app-prettier.mjs

@@ -0,0 +1,27 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadPrettier } from '../sync/format.mjs';
+/** The app's own Prettier, from the first side or the root that installs one, or undefined. */
+export function prettierOf(root, folders) {
+    for (const folder of [...folders, root]) {
+        try {
+            return loadPrettier(folder);
+        }
+        catch { /* the next folder */ }
+    }
+    return undefined;
+}
+/** `text` formatted by the app's Prettier the way `app check --format` judges it, or unchanged when the file is ignored or cannot be formatted. */
+export async function formatted(prettier, root, file, text) {
+    const ignorePath = path.join(root, '.prettierignore');
+    try {
+        const info = await prettier.getFileInfo(file, { ignorePath: fs.existsSync(ignorePath) ? ignorePath : undefined, resolveConfig: true });
+        if (info.ignored || !info.inferredParser)
+            return text;
+        const options = (await prettier.resolveConfig(file, { editorconfig: true, useCache: true })) ?? {};
+        return await prettier.format(text, { ...options, filepath: file });
+    }
+    catch {
+        return text;
+    }
+}

package/codemod/explicit-surface.mjs

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { declarationSurface, isEmittableSource } from '../runtime/scripts/lib/declaration-surface.mjs';
 import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
-import { loadPrettier } from '../sync/format.mjs';
+import { formatted, prettierOf } from './app-prettier.mjs';
 import { applyEdits, importEdits } from './explicit-surface-edit.mjs';
 import { conventionType, MAX_TYPE_LENGTH, renderType } from './explicit-surface-render.mjs';
 import { GENERATED, relativePosix, sideFolders } from './source-tree.mjs';
@@ -212,30 +212,6 @@ async function sideSources(root, side, folder) {
     visit(folder);
     return { files: files.sort(), scope: selects === undefined ? 'walk' : 'canon' };
 }
-/** The app's own Prettier, from the first side or the root that installs one, or undefined. */
-function prettierOf(root, folders) {
-    for (const folder of [...folders, root]) {
-        try {
-            return loadPrettier(folder);
-        }
-        catch { /* the next folder */ }
-    }
-    return undefined;
-}
-/** `text` formatted by the app's Prettier the way `app check --format` judges it, or unchanged when the file is ignored or cannot be formatted. */
-async function formatted(prettier, root, file, text) {
-    const ignorePath = path.join(root, '.prettierignore');
-    try {
-        const info = await prettier.getFileInfo(file, { ignorePath: fs.existsSync(ignorePath) ? ignorePath : undefined, resolveConfig: true });
-        if (info.ignored || !info.inferredParser)
-            return text;
-        const options = (await prettier.resolveConfig(file, { editorconfig: true, useCache: true })) ?? {};
-        return await prettier.format(text, { ...options, filepath: file });
-    }
-    catch {
-        return text;
-    }
-}
 /** The side-relative name a report gives `absolute`. */
 const nameOf = (root, absolute) => relativePosix(root, absolute);
 /** Plans every open file of one program, checks that the rewritten files read no worse than the originals, and returns what each file becomes. */

package/codemod/main.mjs

@@ -14,10 +14,11 @@ import { migrateModuleDefinition, moduleDefinitionMarkdown } from './module-defi
 import { migrateQualityBinding, qualityBindingMarkdown } from './quality-binding.mjs';
 import { migrateSopsRules, sopsRulesMarkdown } from './sops-rules.mjs';
 import { migrateSecretsCache, secretsCacheMarkdown } from './secrets-cache.mjs';
+import { migrateSeedsLayout, seedsLayoutMarkdown } from './seeds-layout.mjs';
 import { migrateThemeTokens, themeTokensMarkdown } from './theme-tokens.mjs';
 import { migrateTierBinding, tierBindingMarkdown } from './tier-binding.mjs';
 /** The codemods `starci app codemod` runs, by name. */
-export const CODEMODS = Object.freeze(['button-intent', 'spacing-roles', 'theme-tokens', 'small-renames', 'page-navigation', 'section-frame', 'surface-card-kinds', 'tier-binding', 'loading-states', 'explicit-surface', 'directive-first', 'secrets-cache', 'module-definition', 'sops-rules', 'quality-binding', 'account-doors']);
+export const CODEMODS = Object.freeze(['button-intent', 'spacing-roles', 'theme-tokens', 'small-renames', 'page-navigation', 'section-frame', 'surface-card-kinds', 'tier-binding', 'loading-states', 'explicit-surface', 'directive-first', 'secrets-cache', 'module-definition', 'sops-rules', 'quality-binding', 'account-doors', 'seeds-layout']);
 /** The arguments of every report-style `starci app codemod`: --execute, --json, --format and --out; any other is refused. */
 export function spacingRolesArguments(argv) {
     const options = { write: false, format: 'markdown' };
@@ -51,6 +52,10 @@ export function spacingRolesArguments(argv) {
 }
 /** One of the report-style codemods run at an app root: its report object and the Markdown of it. */
 function runCodemod(name, root, write) {
+    if (name === 'seeds-layout') {
+        const report = migrateSeedsLayout({ root, write });
+        return { report, markdown: seedsLayoutMarkdown(report) };
+    }
     if (name === 'quality-binding') {
         const report = migrateQualityBinding({ root, write });
         return { report, markdown: qualityBindingMarkdown(report) };
@@ -59,10 +64,6 @@ function runCodemod(name, root, write) {
         const report = migrateSopsRules({ root, write });
         return { report, markdown: sopsRulesMarkdown(report) };
     }
-    if (name === 'module-definition') {
-        const report = migrateModuleDefinition({ root, write });
-        return { report, markdown: moduleDefinitionMarkdown(report) };
-    }
     if (name === 'secrets-cache') {
         const report = migrateSecretsCache({ root, write });
         return { report, markdown: secretsCacheMarkdown(report) };
@@ -126,6 +127,12 @@ async function explicitSurfaceMain(argv, io) {
     const report = await migrateExplicitSurface({ root: path.resolve(io.cwd), write: options.write });
     return emit(options, { report, markdown: explicitSurfaceMarkdown(report) }, io);
 }
+/** `starci app codemod module-definition`: it formats each rewritten definition with the app's Prettier, which is asynchronous. */
+async function moduleDefinitionMain(argv, io) {
+    const options = reportArguments(argv);
+    const report = await migrateModuleDefinition({ root: path.resolve(io.cwd), write: options.write });
+    return emit(options, { report, markdown: moduleDefinitionMarkdown(report) }, io);
+}
 /** `starci app codemod account-doors [--contract]`: the expand migration of the account doors, or (a release later) the contract migration that revokes the old grants. */
 function accountDoorsMain(argv, io) {
     const contract = argv.includes('--contract');
@@ -145,6 +152,8 @@ export function codemodMain(argv, io) {
         return explicitSurfaceMain(rest, io);
     if (name === 'account-doors')
         return accountDoorsMain(rest, io);
+    if (name === 'module-definition')
+        return moduleDefinitionMain(rest, io);
     if (name === undefined || !CODEMODS.includes(name))
         throw new Error(`starci app codemod takes ${CODEMODS.join(' or ')}`);
     const options = reportArguments(rest);

package/codemod/module-definition.d.mts

@@ -1,3 +1,4 @@
+import type { Prettier } from '../sync/format.mjs';
 /** The TypeScript compiler API of the app's own install (loadTypescript), typed by the version this package develops against. */
 type Ts = typeof import('typescript');
 /** One definition the migration rewrites: which form it was written in, the helper it became and the names it exports. */
@@ -41,12 +42,18 @@ export declare function transformModuleDefinition({ ts, text, file }: {
     changes: ModuleDefinitionChange[];
     findings: ModuleDefinitionFinding[];
 };
-/** Preview or apply the rewrite in one app: every `*.module-definition.ts` under its sides, then the dependency in the root package.json. */
-export declare function migrateModuleDefinition({ root, write, ts }: {
+/** What `migrateModuleDefinition` takes: the app root, whether to write, and the compiler and formatter of the app (found in it when left out; `prettier: null` writes the codemod's own layout). */
+export interface ModuleDefinitionOptions {
     root: string;
     write?: boolean;
     ts?: Ts | null;
-}): ModuleDefinitionReport;
+    prettier?: Prettier | null;
+}
+/**
+ * Preview or apply the rewrite in one app: every `*.module-definition.ts` under its sides, each rewritten file formatted by the app's Prettier
+ * (so `app check --format` and the app's hook accept it as written), then the dependency in the root package.json.
+ */
+export declare function migrateModuleDefinition({ root, write, ts, prettier }: ModuleDefinitionOptions): Promise<ModuleDefinitionReport>;
 /** Render the rewrite and what is left for a person as Markdown; JSON consumers read the same report object. */
 export declare function moduleDefinitionMarkdown(report: ModuleDefinitionReport): string;
 export {};

package/codemod/module-definition.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { bundledPins } from '../runtime/scripts/hfs/canon-pins.mjs';
 import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
+import { formatted, prettierOf } from './app-prettier.mjs';
 import { filesUnder, relativePosix, sideFolders } from './source-tree.mjs';
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const KIT = '@starci/nest-kit';
@@ -118,7 +119,7 @@ function readDefinition(ts, source) {
         drop.add(statement);
         if (at === null) {
             at = statement;
-            doc = docOf(ts, source, statement);
+            doc = docOf(ts, source, statement) || docOf(ts, source, builtStatement);
         }
     }
     if (at === null || names.length === 0)
@@ -130,25 +131,34 @@ function readDefinition(ts, source) {
         return unfit(source, builtStatement, 'MODULE_DEFINITION_NAMES', 'another statement of the file reads the builder result or `Host`');
     return { ...read, names: [...names].sort((a, b) => [...EXPORTED].indexOf(a) - [...EXPORTED].indexOf(b)), doc, drop, at, from: 'typed builder' };
 }
-/** The one export of the new definition, laid out the way Prettier prints it at the width of the canon (break the arguments of a call that takes a token, else after the `=`). */
+/** The one export of the new definition, laid out the way Prettier prints it at the width of the canon (one line; else the options object opens on the line of the `=` when that fits; else the call breaks after the `=`). */
 function exportLine(reading, helper) {
     const head = `export const { ${reading.names.join(', ')} } =`;
     const call = `${helper}<${reading.options}>(${reading.token === null ? '' : `{ optionsInjectionToken: ${reading.token} }`})`;
     if (`${head} ${call}`.length <= PRINT_WIDTH)
         return `${head} ${call}`;
-    return reading.token === null ? `${head}\n    ${call}` : `${head} ${helper}<${reading.options}>({\n    optionsInjectionToken: ${reading.token},\n})`;
+    const hug = `${head} ${helper}<${reading.options}>({`;
+    return reading.token !== null && hug.length <= PRINT_WIDTH ? `${hug}\n    optionsInjectionToken: ${reading.token},\n})` : `${head}\n    ${call}`;
 }
-/** The import declaration of `@nestjs/common` without the builder names, or null when nothing else is imported from it. */
-function nestImport(ts, source, statement) {
-    const bindings = statement.importClause?.namedBindings;
-    if (bindings === undefined || !ts.isNamedImports(bindings))
+/** The words of `text` (identifier characters), so a binding is known to be read by its name. */
+const wordsOf = (text) => new Set(text.match(/[\w$]+/g));
+/**
+ * An import declaration without the named bindings the rewrite made unused (read by the dropped statements, by none of the kept ones), or null
+ * when nothing is left of it; `import type` and inline `type` stay as written.
+ */
+function prunedImport(ts, source, statement, before, after) {
+    const clause = statement.importClause;
+    const bindings = clause?.namedBindings;
+    if (clause === undefined || bindings === undefined || !ts.isNamedImports(bindings))
         return statement.getText(source);
-    const kept = bindings.elements.filter((element) => !['ConfigurableModuleBuilder', 'ConfigurableModuleHost'].includes((element.propertyName ?? element.name).text));
+    const kept = bindings.elements.filter((element) => after.has(element.name.text) || !before.has(element.name.text));
     if (kept.length === bindings.elements.length)
         return statement.getText(source);
-    if (kept.length === 0 && statement.importClause?.name === undefined)
+    if (kept.length === 0 && clause.name === undefined)
         return null;
-    return `import { ${kept.map((element) => element.getText(source)).join(', ')} } from "@nestjs/common"`;
+    const named = kept.length === 0 ? '' : `{ ${kept.map((element) => element.getText(source)).join(', ')} }`;
+    const head = [clause.name?.text, named].filter((part) => part !== undefined && part !== '').join(', ');
+    return `import ${clause.isTypeOnly ? 'type ' : ''}${head} from ${statement.moduleSpecifier.getText(source)}`;
 }
 /** Rewrite one definition file's text to the helper form; `text` unchanged when the file holds no definition the codemod can rewrite. */
 export function transformModuleDefinition({ ts, text, file = 'x.module-definition.ts' }) {
@@ -162,13 +172,11 @@ export function transformModuleDefinition({ ts, text, file = 'x.module-definitio
     if ('reason' in read)
         return { ...none, findings: [{ file, line: read.line, code: read.code, reason: read.reason }] };
     const helper = read.representative ? 'defineCapabilityModule' : 'defineConfigurableModule';
-    const imports = [`import { ${helper} } from "${KIT}"`];
     const body = [];
+    const declarations = [];
     for (const statement of source.statements) {
         if (ts.isImportDeclaration(statement)) {
-            const nest = ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === '@nestjs/common' ? nestImport(ts, source, statement) : statement.getText(source);
-            if (nest !== null)
-                imports.push(nest);
+            declarations.push(statement);
             continue;
         }
         if (read.drop.has(statement))
@@ -179,6 +187,9 @@ export function transformModuleDefinition({ ts, text, file = 'x.module-definitio
         }
         body.push(text.slice(statement.pos, statement.end).replace(/^\s*\n/, '').trimEnd());
     }
+    const before = wordsOf(source.statements.filter((statement) => !ts.isImportDeclaration(statement)).map((statement) => statement.getText(source)).join('\n'));
+    const after = wordsOf(body.join('\n'));
+    const imports = [`import { ${helper} } from "${KIT}"`, ...declarations.flatMap((statement) => prunedImport(ts, source, statement, before, after) ?? [])];
     const output = `${imports.join('\n')}\n\n${body.join('\n\n')}\n`;
     return { text: output, changes: [{ file, from: read.from, helper, names: read.names }], findings: [] };
 }
@@ -186,13 +197,17 @@ export function transformModuleDefinition({ ts, text, file = 'x.module-definitio
 function kitVersion() {
     return bundledPins()[KIT]?.version ?? '0.1.0';
 }
-/** Preview or apply the rewrite in one app: every `*.module-definition.ts` under its sides, then the dependency in the root package.json. */
-export function migrateModuleDefinition({ root, write = false, ts = loadTypescript(root, PACKAGE_ROOT) }) {
+/**
+ * Preview or apply the rewrite in one app: every `*.module-definition.ts` under its sides, each rewritten file formatted by the app's Prettier
+ * (so `app check --format` and the app's hook accept it as written), then the dependency in the root package.json.
+ */
+export async function migrateModuleDefinition({ root, write = false, ts = loadTypescript(root, PACKAGE_ROOT), prettier }) {
     if (!ts)
         throw new Error('module-definition needs TypeScript installed in the app or @starci/hfs development checkout');
     const folders = sideFolders(root);
     if (!folders.length)
         throw new Error('module-definition runs at an app root with a be/ directory');
+    const formatter = prettier === undefined ? prettierOf(root, folders) : prettier ?? undefined;
     const packageFile = path.join(root, 'package.json');
     const manifest = fs.existsSync(packageFile) ? JSON.parse(fs.readFileSync(packageFile, 'utf8')) : null; // reason: package.json parsed from disk, only dependencies is read
     const declared = manifest?.dependencies?.[KIT] !== undefined;
@@ -207,7 +222,7 @@ export function migrateModuleDefinition({ root, write = false, ts = loadTypescri
         if (result.text !== original) {
             report.filesChanged.push(file);
             if (write)
-                fs.writeFileSync(target, result.text);
+                fs.writeFileSync(target, formatter === undefined ? result.text : await formatted(formatter, root, target, result.text));
         }
     }
     if (report.filesChanged.length > 0 && !declared && manifest !== null) {

package/codemod/seeds-layout.d.mts

@@ -0,0 +1,36 @@
+/** One seed file the migration moves into a level's `sql/` and declares in its manifest; `drop` when the target already holds its bytes. */
+export interface SeedsLayoutMove {
+    from: string;
+    to: string;
+    entry: string;
+    action: 'move' | 'drop';
+}
+/** One case left for a person. */
+export interface SeedsLayoutFinding {
+    file: string;
+    code: string;
+    reason: string;
+}
+/** The report of a migration (`starci app codemod seeds-layout`). */
+export interface SeedsLayoutReport {
+    schema: string;
+    root: string;
+    write: boolean;
+    environments: string[];
+    moves: SeedsLayoutMove[];
+    created: string[];
+    findings: SeedsLayoutFinding[];
+}
+/**
+ * Migrate an app's seed data into the seed levels of `.starcistacks/` (ruling seed-levels, contexts/project/stacks.md PROJECT-STACKS-12):
+ * `db/seed.sql` moves to the shared level's `sql/reference.sql` and each loose SQL file of `<env>/seeds/` to that level's `sql/`, each
+ * declared in its level's `seeds.yaml` (target the primary database, mode upsert); every level gets its manifest and a `.gitkeep` for each
+ * kind folder that holds nothing. A target with the same bytes drops the old copy; other bytes, a loose seed that is no SQL and a source that
+ * still names an old home are left for a person. A second run finds nothing to do.
+ */
+export declare function migrateSeedsLayout({ root, write }: {
+    root: string;
+    write?: boolean;
+}): SeedsLayoutReport;
+/** Render the migration and what is left for a person as Markdown; JSON consumers read the same report object. */
+export declare function seedsLayoutMarkdown(report: SeedsLayoutReport): string;

package/codemod/seeds-layout.mjs

@@ -0,0 +1,113 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { declaredEnvironments } from '../runtime/scripts/hfs/rules/seeds.mjs';
+import { SEED_FILE } from '../runtime/scripts/hfs/rules/database-constants.mjs';
+import { addSeedEntries, SEED_FOLDERS, SEEDS_KEEP, SEEDS_MANIFEST, SEEDS_SCHEMA, seedLevelDir } from '../runtime/scripts/hfs/stack-seeds-config.mjs';
+import { filesUnder, relativePosix, sideFolders } from './source-tree.mjs';
+/** The lite SQL seed of manifest 3.17 (slot app.db.seed): its rows are every environment's, so it moves to the shared level. */
+const LEGACY_DB_SEED = 'db/seed.sql';
+/** The id and target a moved SQL seed is declared with: the primary database, applied again whenever its content changes. */
+const SQL_TARGET = 'primary';
+/** How a source names an old seed home: the lite seed path, or the seeds folder of an environment read without its sql/ folder. */
+const LEGACY_REFERENCE = /db\/seed\.sql|"\.starcistacks",\s*[A-Za-z_$][\w$]*,\s*"seeds"\)/u;
+const SOURCE = /\.(?:[cm]?[jt]s|json)$/u;
+const isFile = (target) => fs.statSync(target, { throwIfNoEntry: false })?.isFile() === true;
+const isFolder = (target) => fs.statSync(target, { throwIfNoEntry: false })?.isDirectory() === true;
+const entryId = (name) => name.replace(/\.sql$/u, '').toLowerCase().replaceAll(/[^a-z0-9]+/gu, '-').replaceAll(/^-+|-+$/gu, '');
+/** The loose seed files of each declared environment's level (directly in `<env>/seeds/`) and the lite `db/seed.sql`, with where each goes. */
+function legacySeeds(root, environments, findings) {
+    const loose = environments.flatMap((env) => {
+        const level = path.join(root, seedLevelDir(env));
+        if (!isFolder(level))
+            return [];
+        return fs.readdirSync(level, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name !== SEEDS_MANIFEST && entry.name !== SEEDS_KEEP).flatMap((entry) => {
+            const from = `${seedLevelDir(env)}/${entry.name}`;
+            if (entry.name.endsWith('.sql'))
+                return [{ env, from, name: entry.name }];
+            findings.push({ file: from, code: 'SEEDS_LAYOUT_NOT_SQL', reason: `only a SQL seed moves by itself; put it under ${seedLevelDir(env)}/data/ or files/ and declare its target (and, for data, its schema) in ${SEEDS_MANIFEST}` });
+            return [];
+        });
+    });
+    return [...loose, ...(isFile(path.join(root, LEGACY_DB_SEED)) ? [{ env: null, from: LEGACY_DB_SEED, name: path.posix.basename(SEED_FILE) }] : [])];
+}
+/** The sources of the app's sides that still name an old seed home (a seed runner the app owns): each is left for a person. */
+function referenceFindings(root) {
+    return sideFolders(root).flatMap((side) => filesUnder(side, SOURCE)).flatMap((file) => {
+        const line = fs.readFileSync(file, 'utf8').split('\n').findIndex((text) => LEGACY_REFERENCE.test(text));
+        return line === -1 ? [] : [{ file: `${relativePosix(root, file)}:${line + 1}`, code: 'SEEDS_LAYOUT_REFERENCE', reason: 'names the old seed home; read the sql/ folder of .starcistacks/seeds/ and then of .starcistacks/<env>/seeds/ (the scaffold\'s seed runner is the model)' }];
+    });
+}
+/** The placeholders and empty manifests a level lacks: `seeds.yaml`, and a `.gitkeep` in each kind folder that holds nothing. */
+function levelSkeleton(root, env, landed) {
+    const dir = seedLevelDir(env);
+    const manifest = isFile(path.join(root, dir, SEEDS_MANIFEST)) || landed.has(`${dir}/${SEEDS_MANIFEST}`) ? [] : [`${dir}/${SEEDS_MANIFEST}`];
+    const keeps = SEED_FOLDERS.map((kind) => `${dir}/${kind}`).filter((folder) => !landed.has(folder) && (!isFolder(path.join(root, folder)) || fs.readdirSync(path.join(root, folder)).length === 0));
+    return [...manifest, ...keeps.map((folder) => `${folder}/${SEEDS_KEEP}`)];
+}
+/**
+ * Migrate an app's seed data into the seed levels of `.starcistacks/` (ruling seed-levels, contexts/project/stacks.md PROJECT-STACKS-12):
+ * `db/seed.sql` moves to the shared level's `sql/reference.sql` and each loose SQL file of `<env>/seeds/` to that level's `sql/`, each
+ * declared in its level's `seeds.yaml` (target the primary database, mode upsert); every level gets its manifest and a `.gitkeep` for each
+ * kind folder that holds nothing. A target with the same bytes drops the old copy; other bytes, a loose seed that is no SQL and a source that
+ * still names an old home are left for a person. A second run finds nothing to do.
+ */
+export function migrateSeedsLayout({ root, write = false }) {
+    const environments = [...(declaredEnvironments(root)?.keys() ?? [])];
+    const report = { schema: 'starci/seeds-layout-report@1', root, write, environments, moves: [], created: [], findings: [] };
+    const landed = new Set();
+    const entries = new Map();
+    for (const { env, from, name } of legacySeeds(root, environments, report.findings)) {
+        const to = `${seedLevelDir(env)}/sql/${name}`;
+        const source = path.join(root, from);
+        const target = path.join(root, to);
+        if (isFile(target) && !fs.readFileSync(target).equals(fs.readFileSync(source))) {
+            report.findings.push({ file: from, code: 'SEEDS_LAYOUT_CONFLICT', reason: `${to} already holds other data; merge the two by hand and delete ${from}` });
+            continue;
+        }
+        const id = entryId(name);
+        report.moves.push({ from, to, entry: id, action: isFile(target) ? 'drop' : 'move' });
+        entries.set(env, [...(entries.get(env) ?? []), { id, kind: 'sql', path: `sql/${name}`, target: SQL_TARGET, mode: 'upsert' }]);
+        landed.add(`${seedLevelDir(env)}/sql`).add(`${seedLevelDir(env)}/${SEEDS_MANIFEST}`);
+        if (!write)
+            continue;
+        if (isFile(target))
+            fs.rmSync(source);
+        else {
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.renameSync(source, target);
+        }
+    }
+    for (const [env, list] of entries)
+        addSeedEntries(root, env, list, write);
+    for (const env of [null, ...environments])
+        report.created.push(...levelSkeleton(root, env, landed));
+    if (write) {
+        for (const file of report.created) {
+            fs.mkdirSync(path.dirname(path.join(root, file)), { recursive: true });
+            fs.writeFileSync(path.join(root, file), file.endsWith(SEEDS_MANIFEST) ? `schema: ${SEEDS_SCHEMA}\nentries: []\n` : '');
+        }
+    }
+    report.findings.push(...referenceFindings(root));
+    return report;
+}
+const cell = (value) => String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');
+/** Render the migration and what is left for a person as Markdown; JSON consumers read the same report object. */
+export function seedsLayoutMarkdown(report) {
+    const done = report.write ? 'moved' : 'would be moved';
+    const out = ['# seeds-layout', '', `${report.moves.length} seed file(s) ${done}, ${report.created.length} level file(s) ${report.write ? 'created' : 'would be created'}, ${report.findings.length} left for a person.`, ''];
+    if (report.findings.length) {
+        out.push('## Left for a person', '', '| file | code | reason |', '|---|---|---|');
+        for (const finding of report.findings)
+            out.push(`| ${cell(finding.file)} | ${finding.code} | ${cell(finding.reason)} |`);
+        out.push('');
+    }
+    if (report.moves.length) {
+        out.push('## Moved', '', '| from | to | entry | action |', '|---|---|---|---|');
+        for (const item of report.moves)
+            out.push(`| ${cell(item.from)} | ${cell(item.to)} | ${item.entry} | ${item.action} |`);
+        out.push('');
+    }
+    if (report.created.length)
+        out.push('## Created', '', ...report.created.map((file) => `- ${file}`), '');
+    return `${out.join('\n')}\n`;
+}