@starci/hfs 5.4.0 → 5.5.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # 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`).

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

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/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) };

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`;
+}

package/codemod/sops-rules.d.mts

@@ -24,7 +24,7 @@ export declare function managedPathRegex(from: string): string;
 /**
  * Migrate a legacy `.sops.yaml` to the form `starci app secret init --env` writes (public recipients only, a rule per member spelling): a rule whose
  * path_regex matches the legacy `.enc` spelling alone also matches `.enc.yaml`, the spelling `secret set` writes, which sops otherwise refuses with
- * no creation rule. Recipients and the other rules are kept; nothing private is read or written.
+ * no creation rule. Recipients, the other rules and the comment header the file opens with (the managed header of `secret init`) are kept; nothing private is read or written.
  */
 export declare function migrateSopsRules({ root, write }: {
     root: string;

package/codemod/sops-rules.mjs

@@ -15,19 +15,24 @@ export function managedPathRegex(from) {
         return CURRENT;
     return /secrets/.test(from) && from.endsWith(LEGACY_END) ? `${from.slice(0, -LEGACY_END.length)}${MODERN_END}` : from;
 }
+/** The comment lines a file opens with (its managed header among them), which a rewrite of the YAML body keeps as written. */
+function leadingComments(text) {
+    return text.replace(/^((?:[ \t]*(?:#[^\n]*)?\r?\n)*)[\s\S]*$/, '$1');
+}
 /**
  * Migrate a legacy `.sops.yaml` to the form `starci app secret init --env` writes (public recipients only, a rule per member spelling): a rule whose
  * path_regex matches the legacy `.enc` spelling alone also matches `.enc.yaml`, the spelling `secret set` writes, which sops otherwise refuses with
- * no creation rule. Recipients and the other rules are kept; nothing private is read or written.
+ * no creation rule. Recipients, the other rules and the comment header the file opens with (the managed header of `secret init`) are kept; nothing private is read or written.
  */
 export function migrateSopsRules({ root, write = false }) {
     const report = { schema: 'starci/sops-rules-report@1', root, write, file: FILE, changes: [], findings: [] };
     const target = path.join(root, FILE);
     if (!fs.existsSync(target))
         return report;
+    const text = fs.readFileSync(target, 'utf8');
     let config;
     try {
-        config = parseYaml(fs.readFileSync(target, 'utf8'));
+        config = parseYaml(text);
     }
     catch {
         config = null;
@@ -46,7 +51,7 @@ export function migrateSopsRules({ root, write = false }) {
         rule.path_regex = to;
     });
     if (report.changes.length > 0 && write)
-        fs.writeFileSync(target, stringifyYaml(config));
+        fs.writeFileSync(target, `${leadingComments(text)}${stringifyYaml(config)}`);
     return report;
 }
 const cell = (value) => String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');

package/lint/run.d.mts

@@ -15,8 +15,9 @@ export interface LinterRun {
 }
 /**
  * What a linter run is asked for. `list` is the files an ESLint run lints (cwd-relative, posix) when they are named one by one: they go to the child
- * through a file, never the command line, and `args` then holds the options alone. `files` is the number of source files the run judges, which the
- * heavy-command budget of the ESLint kind scales with (a list names its own count).
+ * through a file, never the command line, and `args` then holds the options alone. `files` is the number of source files the child's work is made of,
+ * which the heavy-command budget of the ESLint kind scales with: the typed program and the project graph of a side are built whole for a named list
+ * too, so a list run of a side whose scope is known names the side's count; without `files` a list names its own count.
  */
 export interface LinterSpec {
     cwd: string;
@@ -134,8 +135,8 @@ export interface CachedLinters {
 }
 /**
  * ESLint and stylelint through the result cache: per side, the files the records cannot vouch for go to the very launcher, chunking and result
- * validation of a full run (eslintRepository), the rest take their records. The answer has the shape of eslintRepository's, plus the stylelint
- * results, so the lint report is built the same way from either.
+ * validation of a full run (eslintRepository), the rest take their records; then the root packages, linted whole. Each scope runs on its own
+ * (scopeFailure). The answer has the shape of eslintRepository's, plus the stylelint results, so the lint report is built the same way from either.
  */
 export declare function cachedLinters({ repoRoot, app, side: only, run, session }: {
     repoRoot: string;

package/lint/run.mjs

@@ -84,7 +84,7 @@ export async function runLinter({ cwd, pkg, bin, args, bound = null, list, files
         fs.writeFileSync(job, JSON.stringify({ files: list ?? ['.'], fix: args.includes('--fix'), ...(snapshotFile === null || graph === undefined ? {} : { graph: { out: snapshotFile, canons: graph } }) }));
         childArgs = [LIST_RUNNER, job];
     }
-    const count = list?.length ?? files;
+    const count = files ?? list?.length;
     let run;
     let handed;
     try {
@@ -365,8 +365,10 @@ async function launchEslint({ app, repoRoot, opts, changed, existing, run = runL
         // the child that builds the canon's project graph for its rules hands the snapshot out when the caller keeps the graph findings (the cache); the packages are no side folder and have no graph
         const graph = handOutGraph && !packages ? graphCanonsOf(repoRoot, cwd, side) : undefined;
         // The files of a diff go to ONE child through a file (a diff of hundreds of long paths outgrows the Windows command line, and each extra
-        // child would build the whole TypeScript program again); the whole side is a single directory argument.
-        const launch = Promise.resolve().then(() => run(changed ? { cwd, pkg: 'eslint', bin: 'eslint', args: head, list: sources, bound: repoRoot, ...(graph === undefined ? {} : { graph }) } : { cwd, pkg: 'eslint', bin: 'eslint', args: [...head, packages ? PACKAGES : '.'], files: expected.length, bound: repoRoot, ...(graph === undefined ? {} : { graph }) }));
+        // child would build the whole TypeScript program again); the whole side is a single directory argument. Either child builds the typed program
+        // and the project graph of the whole side, so its liveness budget scales with the side's scope when the caller knows it, never with the diff alone.
+        const programFiles = known?.length ?? expected.length;
+        const launch = Promise.resolve().then(() => run(changed ? { cwd, pkg: 'eslint', bin: 'eslint', args: head, list: sources, files: programFiles, bound: repoRoot, ...(graph === undefined ? {} : { graph }) } : { cwd, pkg: 'eslint', bin: 'eslint', args: [...head, packages ? PACKAGES : '.'], files: programFiles, bound: repoRoot, ...(graph === undefined ? {} : { graph }) }));
         launches.push({ side, cwd, expected, run: launch.catch(spawnFailure) });
     }
     return launches;
@@ -489,10 +491,20 @@ export function gitBaseToken(repoRoot) {
     }
     return 'no-base';
 }
+/**
+ * A scope whose linter reached no complete measurement (a child ended by its liveness budget, a capture cut short) is a tool error of that scope, and the
+ * next scope still runs: the root packages are judged whatever became of the back end. Nothing of the failed scope is recorded (its records are written
+ * only after its child completed). A hold of the host (HOST_HELD, HEAVY_DEFERRED) still ends the run, since no scope would be admitted either.
+ */
+function scopeFailure(error, scope) {
+    if (!isNodeExecutionRefusal(error) || isHostHeld(error) || error.code === 'HEAVY_DEFERRED')
+        throw error;
+    return `eslint did not complete in ${scope}/: ${String(error.message).split('\n')[0]}`;
+}
 /**
  * ESLint and stylelint through the result cache: per side, the files the records cannot vouch for go to the very launcher, chunking and result
- * validation of a full run (eslintRepository), the rest take their records. The answer has the shape of eslintRepository's, plus the stylelint
- * results, so the lint report is built the same way from either.
+ * validation of a full run (eslintRepository), the rest take their records; then the root packages, linted whole. Each scope runs on its own
+ * (scopeFailure). The answer has the shape of eslintRepository's, plus the stylelint results, so the lint report is built the same way from either.
  */
 export async function cachedLinters({ repoRoot, app, side: only, run, session }) {
     const eslint = { findings: [], errors: [], raw: [], engine: { sides: {} } };
@@ -514,23 +526,31 @@ export async function cachedLinters({ repoRoot, app, side: only, run, session })
             continue;
         }
         const styled = side === STYLE_SIDE;
-        const outcome = await lintSide({
-            session, side, sideRoot: cwd, scope, stylesheets: styled ? stylesheetsOf(cwd) : [],
-            canons, styleCanon: styled ? await styleDeclaration({ repoRoot, cwd }) : null, typescript: () => loadAppTypeScript(cwd), extraKey: '', gitToken, full, write: true,
-            eslint: async (files) => {
-                const listed = files === null ? null : files.map((file) => `${side}/${file}`);
-                const sub = await eslintRepository({ repoRoot, app, opts: { side }, changed: listed, existing: listed ?? [], run, scopes: { [side]: scope }, handOutGraph: true });
-                return { results: sub.raw, errors: sub.errors, ...(sub.graphs[side] === undefined ? {} : { graph: sub.graphs[side] }) };
-            },
-            stylelint: styled ? async (files) => {
-                const linted = await (run ?? runLinter)({ cwd, pkg: 'stylelint', bin: 'stylelint', args: [...(files ?? [STYLE_GLOB]), '--formatter', 'json'] });
-                const appRelative = appRelativeMessages(STYLE_SIDE, cwd);
-                for (const result of linted.results ?? [])
-                    for (const warning of result.warnings ?? [])
-                        warning.text = appRelative(warning.text);
-                return { results: (linted.results ?? []), errors: linted.error ? [linted.error] : [] };
-            } : null,
-        });
+        let outcome;
+        try {
+            outcome = await lintSide({
+                session, side, sideRoot: cwd, scope, stylesheets: styled ? stylesheetsOf(cwd) : [],
+                canons, styleCanon: styled ? await styleDeclaration({ repoRoot, cwd }) : null, typescript: () => loadAppTypeScript(cwd), extraKey: '', gitToken, full, write: true,
+                eslint: async (files) => {
+                    const listed = files === null ? null : files.map((file) => `${side}/${file}`);
+                    const sub = await eslintRepository({ repoRoot, app, opts: { side }, changed: listed, existing: listed ?? [], run, scopes: { [side]: scope }, handOutGraph: true });
+                    return { results: sub.raw, errors: sub.errors, ...(sub.graphs[side] === undefined ? {} : { graph: sub.graphs[side] }) };
+                },
+                stylelint: styled ? async (files) => {
+                    const linted = await (run ?? runLinter)({ cwd, pkg: 'stylelint', bin: 'stylelint', args: [...(files ?? [STYLE_GLOB]), '--formatter', 'json'] });
+                    const appRelative = appRelativeMessages(STYLE_SIDE, cwd);
+                    for (const result of linted.results ?? [])
+                        for (const warning of result.warnings ?? [])
+                            warning.text = appRelative(warning.text);
+                    return { results: (linted.results ?? []), errors: linted.error ? [linted.error] : [] };
+                } : null,
+            });
+        }
+        catch (error) {
+            eslint.errors.push(scopeFailure(error, side));
+            eslint.engine.sides[side] = { files: 0 };
+            continue;
+        }
         sides.push({ side, stats: outcome.stats });
         for (const message of outcome.errors)
             (message.startsWith('stylelint ') ? style.errors : eslint.errors).push(message);
@@ -544,11 +564,17 @@ export async function cachedLinters({ repoRoot, app, side: only, run, session })
     }
     // The root packages are small and have no result records: they are linted whole on every run, through the same launcher.
     if ((only === undefined || only === PACKAGES) && hasPackagesLint(repoRoot)) {
-        const linted = await eslintRepository({ repoRoot, app, opts: { side: PACKAGES }, run });
-        eslint.errors.push(...linted.errors);
-        eslint.raw.push(...linted.raw);
-        eslint.findings.push(...linted.findings);
-        eslint.engine.sides[PACKAGES] = linted.engine.sides[PACKAGES] ?? { files: 0 };
+        try {
+            const linted = await eslintRepository({ repoRoot, app, opts: { side: PACKAGES }, run });
+            eslint.errors.push(...linted.errors);
+            eslint.raw.push(...linted.raw);
+            eslint.findings.push(...linted.findings);
+            eslint.engine.sides[PACKAGES] = linted.engine.sides[PACKAGES] ?? { files: 0 };
+        }
+        catch (error) {
+            eslint.errors.push(scopeFailure(error, PACKAGES));
+            eslint.engine.sides[PACKAGES] = { files: 0 };
+        }
     }
     session.report(lintFamilyReport(sides));
     return { eslint, stylelint: style, sides };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "5.4.0",
+  "version": "5.5.0",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/release/lint-report.mjs

@@ -5,7 +5,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { firstLine, tool } from '../stack/context.mjs';
-const LINT_SIDES = ['be', 'fe'];
+import { PACKAGES, PACKAGES_CONFIG } from '../lint/run.mjs';
+const LINT_SIDES = ['be', 'fe', PACKAGES];
 const MERGED_REPORT = 'reports/lint.sonar.json';
 const sideReport = (side) => `reports/lint.${side}.sonar.json`;
 /** CI merge: rules unique by id (last one wins, first position kept), issues concatenated in side order. */
@@ -14,8 +15,8 @@ function mergeSonarReports(reports) {
     const issues = reports.flatMap((report) => report.issues);
     return { rules, issues };
 }
-/** The sides the app has: a be/ or fe/ folder beside the app root. */
-const sidesOf = (root) => LINT_SIDES.filter((side) => fs.existsSync(path.join(root, side)));
+/** The lint scopes the app has: a be/ or fe/ folder beside the app root, and its root packages when it has their managed config. */
+const sidesOf = (root) => LINT_SIDES.filter((side) => fs.existsSync(path.join(root, side)) && (side !== PACKAGES || fs.existsSync(path.join(root, PACKAGES_CONFIG))));
 /**
  * Runs `starci app check --gate lint --side <side> --out <file>` for every side the app has, then writes reports/lint.sonar.json.
  * `launch` turns an argv into [command, args] for the platform. Returns { pass, text }: the honest log of every lint run and the verdict.