@starci/hfs 5.4.0 → 5.5.0

package/runtime/scripts/hfs/stack-seeds-config.mjs

@@ -0,0 +1,239 @@
+// stack-seeds-config.mjs - reads and judges a seed level's manifest (`seeds.yaml`, schema starci/seeds@1), the declaration of the data an app
+// seeds (contexts/project/stacks.md PROJECT-STACKS-12). A level is `.starcistacks/seeds/` (shared, every environment, first) or
+// `.starcistacks/<env>/seeds/` (that environment only); each holds the manifest and the folders `sql/`, `data/` and `files/`. One entry is
+// `{ id, kind, path, target, mode, after?, schema?, reason? }`: a `sql` entry is idempotent DML the harness runs on the database `target`
+// names, a `data` entry is a document (or a folder of them) an app command (`target`, an argv list) loads after it validates against the JSON
+// schema `schema` names, a `test-account` entry is the one data entry of an environment's level that declares a test account (with its
+// `reason`), a `files` entry is assets for the bucket `target` names. A document names a secret as `{ "secret": "seeds-<name>" }`, a sealed
+// member of the environment (`.starcistacks/<env>/secrets/seeds-<name>.enc.yaml`) the seed step opens in memory, never a value. The same
+// normaliser serves `starci app check` (R375) and the seed step of the stack verbs, so a manifest the check passes is one the step applies.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseYaml, stringifyYaml } from '../../engine/yaml.mjs';
+import { closedFields, collector, patternField } from './stack-config-kit.mjs';
+export const SEEDS_SCHEMA = 'starci/seeds@1';
+/** The folder name of a seed level, at `.starcistacks/` and under each environment. */
+export const SEEDS_DIR = 'seeds';
+/** The manifest of a level. */
+export const SEEDS_MANIFEST = 'seeds.yaml';
+/** The kinds of entry; each lives in the folder `kindFolder` names. */
+export const SEED_KINDS = Object.freeze(['sql', 'data', 'test-account', 'files']);
+/** The folders of a level. */
+export const SEED_FOLDERS = Object.freeze(['sql', 'data', 'files']);
+/** `once`: applied a single time; `upsert`: applied again whenever its content hash changes. */
+export const SEED_MODES = Object.freeze(['once', 'upsert']);
+/** The placeholder that keeps an empty seed folder tracked. */
+export const SEEDS_KEEP = '.gitkeep';
+const ID = /^[a-z0-9][a-z0-9-]{0,62}$/u;
+const NAME = /^[a-z][a-z0-9_-]{0,62}$/u;
+const ENTRY_FIELDS = ['id', 'kind', 'path', 'target', 'mode', 'after', 'schema', 'reason'];
+const DOCUMENT = /\.(?:json|ya?ml)$/u;
+/** The name of a sealed member a seed document may reference. */
+export const SEED_SECRET_MEMBER = /^seeds-[a-z0-9][a-z0-9-]{0,62}$/u;
+/** The folder of a level a kind's paths live in: a test account is data. */
+export const kindFolder = (kind) => (kind === 'test-account' ? 'data' : kind);
+/** True for an entry the app command loads as documents: `data` and `test-account`. */
+export const isDocumentEntry = (entry) => entry.kind === 'data' || entry.kind === 'test-account';
+/** The sealed member file of `member` in the environment `env`, app-relative. */
+export const seedMemberFile = (env, member) => `.starcistacks/${env}/secrets/${member}.enc.yaml`;
+/** The app-relative folder of a level: the shared one when `env` is null. */
+export const seedLevelDir = (env) => (env === null ? `.starcistacks/${SEEDS_DIR}` : `.starcistacks/${env}/${SEEDS_DIR}`);
+const isFile = (target) => fs.statSync(target, { throwIfNoEntry: false })?.isFile() === true;
+const isFolder = (target) => fs.statSync(target, { throwIfNoEntry: false })?.isDirectory() === true;
+/** Every file under `folder` (absolute) as a path relative to `base`, posix and sorted, the placeholders aside; a missing folder holds none. */
+export function filesBelow(base, folder) {
+    if (!isFolder(folder))
+        return [];
+    return fs.readdirSync(folder, { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name !== SEEDS_KEEP)
+        .map((entry) => path.relative(base, path.join(entry.parentPath, entry.name)).split(path.sep).join('/'))
+        .sort((a, b) => (a < b ? -1 : Number(a > b)));
+}
+/** The level-relative files an entry covers: its path when it is a file, every file below it when it is a folder. */
+export function entryFiles(levelRoot, entry) {
+    const target = path.join(levelRoot, entry.path);
+    return isFile(target) ? [entry.path] : filesBelow(levelRoot, target);
+}
+/** The content hash of an entry: its kind, target, mode and every file it covers, by path and bytes. */
+export function entryDigest(levelRoot, entry) {
+    const hash = crypto.createHash('sha256').update(JSON.stringify([entry.kind, entry.target, entry.mode]));
+    for (const file of entryFiles(levelRoot, entry))
+        hash.update('\0').update(file).update('\0').update(fs.readFileSync(path.join(levelRoot, file)));
+    return hash.digest('hex');
+}
+function targetOf(c, at, kind, value) {
+    if (kind === 'data' || kind === 'test-account') {
+        if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== 'string' || item === ''))
+            c.problem(at, 'must be the argv list of the app command that loads the data (never a shell line)');
+        return Array.isArray(value) ? value.map(String) : [];
+    }
+    patternField(c, at, value, NAME);
+    return String(value ?? '');
+}
+function entryOf(c, at, value, levelRoot, ids) {
+    if (!closedFields(c, at, value, ENTRY_FIELDS, 'seed entry'))
+        return null;
+    const raw = value;
+    if (patternField(c, `${at}.id`, raw.id, ID) && ids.has(String(raw.id)))
+        c.problem(`${at}.id`, `${String(raw.id)} is declared twice`);
+    ids.add(String(raw.id));
+    const kind = SEED_KINDS.find((item) => item === raw.kind);
+    if (kind === undefined) {
+        c.problem(`${at}.kind`, `must be one of ${SEED_KINDS.join(', ')}`);
+        return null;
+    }
+    const file = typeof raw.path === 'string' ? raw.path : '';
+    const folder = kindFolder(kind);
+    if (!file.startsWith(`${folder}/`) || path.posix.normalize(file) !== file || file.includes('\\'))
+        c.problem(`${at}.path`, `must be a path under ${folder}/ of the level`);
+    else if (!fs.existsSync(path.join(levelRoot, file)))
+        c.problem(`${at}.path`, `${file} does not exist in the level`);
+    const mode = SEED_MODES.find((item) => item === raw.mode);
+    if (mode === undefined)
+        c.problem(`${at}.mode`, `must be one of ${SEED_MODES.join(', ')}`);
+    const after = raw.after === undefined ? [] : raw.after;
+    if (!Array.isArray(after) || after.some((item) => typeof item !== 'string'))
+        c.problem(`${at}.after`, 'must be a list of entry ids');
+    const documents = isDocumentEntry({ kind });
+    if (documents && (typeof raw.schema !== 'string' || raw.schema === ''))
+        c.problem(`${at}.schema`, 'must name the JSON schema the app declares for the data, app-root relative');
+    if (!documents && raw.schema !== undefined)
+        c.problem(`${at}.schema`, 'is a field of a data or test-account entry only');
+    if (kind === 'test-account' && (typeof raw.reason !== 'string' || raw.reason.trim() === ''))
+        c.problem(`${at}.reason`, 'must say why this environment holds a test account');
+    if (kind !== 'test-account' && raw.reason !== undefined)
+        c.problem(`${at}.reason`, 'is a field of a test-account entry only');
+    return {
+        id: String(raw.id), kind, path: file, target: targetOf(c, `${at}.target`, kind, raw.target), mode: mode ?? 'upsert',
+        after: Array.isArray(after) ? after.map(String) : [], schema: documents && typeof raw.schema === 'string' ? raw.schema : null,
+        reason: kind === 'test-account' && typeof raw.reason === 'string' ? raw.reason : null,
+    };
+}
+/** The entries in apply order: manifest order, each after the entries it names; an unknown id or a cycle is a problem. */
+function applyOrder(c, entries, shared) {
+    const own = new Set(entries.map((entry) => entry.id));
+    for (const entry of entries)
+        for (const id of entry.after)
+            if (!own.has(id) && !shared.has(id))
+                c.problem(`entries.${entry.id}.after`, `${id} is no entry of this level or the shared level`);
+    const done = new Set();
+    const order = [];
+    let pending = entries;
+    while (pending.length > 0) {
+        const ready = pending.filter((entry) => entry.after.every((id) => !own.has(id) || done.has(id)));
+        if (ready.length === 0) {
+            c.problem('entries', `the after lists of ${pending.map((entry) => entry.id).join(', ')} form a cycle`);
+            return [...order, ...pending];
+        }
+        for (const entry of ready) {
+            order.push(entry);
+            done.add(entry.id);
+        }
+        pending = pending.filter((entry) => !done.has(entry.id));
+    }
+    return order;
+}
+/**
+ * Normalises the parsed manifest of the level at `levelRoot`; `shared` holds the ids of the shared level an environment's entries may follow,
+ * and is null for the shared level itself, which declares no test account (an environment's level declares at most one).
+ */
+export function normalizeSeeds(doc, levelRoot, shared = new Set()) {
+    const c = collector();
+    if (!closedFields(c, 'manifest', doc, ['schema', 'entries'], 'seeds'))
+        return { entries: [], problems: c.problems };
+    const raw = doc;
+    if (raw.schema !== SEEDS_SCHEMA)
+        c.problem('schema', `must be ${SEEDS_SCHEMA}`);
+    const list = raw.entries ?? [];
+    if (!Array.isArray(list)) {
+        c.problem('entries', 'must be a list');
+        return { entries: [], problems: c.problems };
+    }
+    const ids = new Set();
+    const entries = list.flatMap((value, index) => entryOf(c, `entries[${index}]`, value, levelRoot, ids) ?? []);
+    const accounts = entries.filter((entry) => entry.kind === 'test-account').map((entry) => entry.id);
+    if (shared === null && accounts.length > 0)
+        c.problem('entries', `${accounts.join(', ')}: the shared level declares no test account; it belongs to the one environment that holds it`);
+    if (accounts.length > 1)
+        c.problem('entries', `${accounts.join(', ')}: a level declares at most one test account`);
+    return { entries: applyOrder(c, entries, shared ?? new Set()), problems: c.problems };
+}
+/** Reads and judges the level of `env` (null: the shared level) at `repoRoot`; a level without a manifest has no entries. */
+export function readSeedLevel(repoRoot, env, shared = new Set()) {
+    const dir = seedLevelDir(env);
+    const file = path.join(repoRoot, dir, SEEDS_MANIFEST);
+    if (!isFile(file))
+        return { dir, env, entries: [], problems: [] };
+    let doc;
+    try {
+        doc = parseYaml(fs.readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        return { dir, env, entries: [], problems: [{ at: 'manifest', message: `does not parse: ${String(error).split('\n')[0]}` }] };
+    }
+    return { dir, env, ...normalizeSeeds(doc ?? {}, path.join(repoRoot, dir), env === null ? null : shared) };
+}
+/** The documents of a data or test-account entry: every JSON or YAML file it covers, parsed. */
+export function seedDocuments(levelRoot, entry) {
+    return entryFiles(levelRoot, entry).filter((file) => DOCUMENT.test(file)).map((file) => {
+        const text = fs.readFileSync(path.join(levelRoot, file), 'utf8');
+        try {
+            return { path: file, doc: file.endsWith('.json') ? JSON.parse(text) : parseYaml(text) };
+        }
+        catch (error) {
+            return { path: file, error: String(error).split('\n')[0] ?? '' };
+        }
+    });
+}
+/** The member a value references when it is a secret reference (`{ "secret": "<member>" }` and nothing else), else null. */
+export function secretReference(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const keys = Object.keys(value);
+    const member = value.secret;
+    return keys.length === 1 && typeof member === 'string' ? member : null;
+}
+/** Every member the secret references of a document name, in document order, once each. */
+export function secretReferences(doc) {
+    const found = [];
+    const visit = (value) => {
+        const member = secretReference(value);
+        if (member !== null) {
+            if (!found.includes(member))
+                found.push(member);
+            return;
+        }
+        if (value !== null && typeof value === 'object')
+            for (const item of Object.values(value))
+                visit(item);
+    };
+    visit(doc);
+    return found;
+}
+/** A copy of `doc` with every secret reference replaced by what `resolve` answers for its member. */
+export function resolveSecrets(doc, resolve) {
+    const member = secretReference(doc);
+    if (member !== null)
+        return resolve(member);
+    if (Array.isArray(doc))
+        return doc.map((item) => resolveSecrets(item, resolve));
+    if (doc !== null && typeof doc === 'object')
+        return Object.fromEntries(Object.entries(doc).map(([key, item]) => [key, resolveSecrets(item, resolve)]));
+    return doc;
+}
+/**
+ * Declares `entries` in the manifest of the level of `env` (null: the shared level), creating the manifest when the level has none; an id the
+ * manifest already holds is kept as it is. Answers the ids it added (none are written when `write` is false).
+ */
+export function addSeedEntries(repoRoot, env, entries, write = true) {
+    const file = path.join(repoRoot, seedLevelDir(env), SEEDS_MANIFEST);
+    const doc = (isFile(file) ? parseYaml(fs.readFileSync(file, 'utf8')) : null);
+    const held = Array.isArray(doc?.entries) ? doc.entries : [];
+    const added = entries.filter((entry) => !held.some((item) => item.id === entry.id));
+    if (added.length > 0 && write) {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, stringifyYaml({ schema: SEEDS_SCHEMA, ...doc, entries: [...held, ...added] }));
+    }
+    return added.map((entry) => entry.id);
+}

package/runtime/scripts/hfs/view.d.mts

@@ -19,6 +19,22 @@ export interface HfsView {
     ownerOf: (file: string) => string | null;
     allows: (file: string) => AllowsResult | null;
     slot: OpenedHfs['slot'];
+    /** The vocabulary a root workspace package declares for itself (`starci` of its manifest); only the view of the root packages has it. */
+    packageContract?: (file: string) => PackageContract | null;
+}
+/** A type a root package declares: its name and the file of the package that declares it, relative to the app root. */
+export interface PackageDeclaredType {
+    readonly name: string;
+    readonly file: string;
+}
+/**
+ * What a root workspace package declares in the `starci` key of its own `package.json`, since it cannot import the app's
+ * `platform/errors` or its `GraphQLResponse<T>`: `errorBase` is the class its errors derive from, `outcome` its one result union, each
+ * `{ name, file }` with `file` relative to the package folder.
+ */
+export interface PackageContract {
+    readonly errorBase?: PackageDeclaredType;
+    readonly outcome?: PackageDeclaredType;
 }
 /**
  * The view of the app folder on disk at `repoRoot`, against the manifest under `runtimeRoot`: a side folder (be/, fe/) finds the
@@ -43,6 +59,15 @@ export declare const declaredHfsView: ({ runtimeRoot, declaration, repoRoot, sid
     repoRoot: string;
     side: string;
 }) => HfsView;
+/**
+ * The contract of the package at `packageDir` (app-root relative, `packages/<pkg>`), read from the `starci` key of its manifest. A
+ * declaration that is not `{ name, file }` with an identifier name and a file inside `src/` stops the lint, because a rule must not guess.
+ *
+ * @param {string} repoRoot - The absolute app root.
+ * @param {string} packageDir - The package folder, relative to the app root.
+ * @returns {object} The declared error base and outcome union, each with its file relative to the app root.
+ */
+export declare const readPackageContract: (repoRoot: string, packageDir: string) => PackageContract;
 /**
  * The view of the root packages of the app at `repoRoot` (the app root, where the root `eslint.config.mjs` lives), for the laws of `side`.
  *

package/runtime/scripts/hfs/view.mjs

@@ -2,6 +2,7 @@
 // their rules (`settings.starci.hfs`). Both @starci/eslint-canon-be and @starci/eslint-canon-fe ship a byte copy of this file in their
 // runtime/ bundle (scripts/hfs/sync-runtime.mjs), so a path-scoped rule in either package asks the SAME resolver the
 // architecture machine and `starci app check` use, and never tests a path with a regular expression of its own.
+import fs from 'node:fs';
 import path from 'node:path';
 import { allowsFile } from './allows.mjs';
 import { openHfs } from './slots.mjs';
@@ -70,6 +71,36 @@ export const openHfsView = ({ runtimeRoot, repoRoot }) => hfsView(openHfs({ root
  * @returns {object} The frozen view.
  */
 export const declaredHfsView = ({ runtimeRoot, declaration, repoRoot, side }) => hfsView(openHfs({ root: runtimeRoot, declaration, side }), repoRoot);
+const CONTRACT_KEYS = ['errorBase', 'outcome'];
+/**
+ * The contract of the package at `packageDir` (app-root relative, `packages/<pkg>`), read from the `starci` key of its manifest. A
+ * declaration that is not `{ name, file }` with an identifier name and a file inside `src/` stops the lint, because a rule must not guess.
+ *
+ * @param {string} repoRoot - The absolute app root.
+ * @param {string} packageDir - The package folder, relative to the app root.
+ * @returns {object} The declared error base and outcome union, each with its file relative to the app root.
+ */
+export const readPackageContract = (repoRoot, packageDir) => {
+    const manifestPath = path.join(repoRoot, packageDir, 'package.json');
+    const manifest = (fs.existsSync(manifestPath) ? JSON.parse(fs.readFileSync(manifestPath, 'utf8')) : null);
+    const declared = manifest?.starci;
+    if (declared === undefined)
+        return {};
+    if (typeof declared !== 'object' || declared === null)
+        throw new Error(`${packageDir}/package.json: "starci" is an object ({ errorBase, outcome })`);
+    const contract = {};
+    for (const key of CONTRACT_KEYS) {
+        const entry = declared[key];
+        if (entry === undefined)
+            continue;
+        const { name, file } = (typeof entry === 'object' && entry !== null ? entry : {});
+        if (typeof name !== 'string' || !/^[A-Za-z_$][\w$]*$/.test(name) || typeof file !== 'string' || !/^src\/(?:[\w.-]+\/)*[\w.-]+\.ts$/.test(file)) {
+            throw new Error(`${packageDir}/package.json: "starci.${key}" is { "name": "<Identifier>", "file": "src/<path>.ts" }`);
+        }
+        contract[key] = Object.freeze({ name, file: `${packageDir}/${file}` });
+    }
+    return Object.freeze(contract);
+};
 /**
  * The view of the root workspace packages of an app (`packages/<pkg>/src/**`, slots app.packages and app.module-registry), as the lint of one
  * side sees them: the rule parameters, the apps and the Grammar of `side` (a package is judged by the laws of the side whose subpath a file
@@ -103,6 +134,15 @@ function packagesView(opened, repoRoot, side) {
         const relative = rel(file);
         return slot !== undefined && ROOT_PACKAGE_SLOTS.has(slot) ? relative.split('/').slice(0, 2).join('/') : null;
     };
+    const contracts = new Map();
+    const packageContract = (file) => {
+        const dir = packageOf(file);
+        if (dir === null)
+            return null;
+        if (!contracts.has(dir))
+            contracts.set(dir, readPackageContract(repoRoot, dir));
+        return contracts.get(dir);
+    };
     return Object.freeze({
         repoRoot,
         profile: side,
@@ -121,6 +161,7 @@ function packagesView(opened, repoRoot, side) {
         ownerOf: () => null,
         allows: (file) => allowsFile(opened, rel(file)),
         slot: (id) => opened.slot(id),
+        packageContract,
     });
 }
 /**

package/scaffold/add-app.mjs

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { loadSlotManifest, readRepoDeclaration, resolveAppDeclaration, } from "../runtime/scripts/hfs/slots.mjs";
-import { imageFiles, render, TEMPLATES_DIR } from "../sync/index.mjs";
+import { appSource, imageFiles, render, TEMPLATES_DIR } from "../sync/index.mjs";
 import { ScaffoldError, pascalOf } from "./service.mjs";
 import { PARTIAL_VARIABLES, coreFeApps, jsonText, packageJsonText } from "./app.mjs";
 /** The shared fe app core (modules/api, auth, toast, redux, the providers, the hooks): the base tree, then the edition overlay. */
@@ -121,7 +121,7 @@ export function addApp({ root, name }) {
     const planned = [...planAppTemplates(repo, name), ...planWorkspaceManifests(root, repo, repo.sides.fe.apps, name)];
     const declaration = JSON.parse(fs.readFileSync(declarationFile, "utf8"));
     declaration.sides.fe.apps.push({ name, kind: "next" });
-    const image = imageFiles(resolveAppDeclaration(manifest, declaration)).find((file) => file.path === `${targetBase}/Dockerfile`);
+    const image = imageFiles(resolveAppDeclaration(manifest, declaration), appSource(root)).find((file) => file.path === `${targetBase}/Dockerfile`);
     if (!image && repo.edition !== "lite")
         throw new ScaffoldError("HFS_ADD_TEMPLATE_MISSING", `the Dockerfile of front-end app ${name} did not render`);
     if (image)

package/scaffold/add-cli-lite.mjs

@@ -43,19 +43,31 @@ export class RunCli extends CommandRunner {
     }
 }
 `;
-const SEED_RUN = `import { CommandRunner, SubCommand } from "nest-commander"
-import { SeedRunnerService } from "@modules/platform/database"
+const SEED_RUN = `import { CommandRunner, Option, SubCommand } from "nest-commander"
+import { DEFAULT_SEED_ENV, SeedRunnerService } from "@modules/platform/database"
+
+/** The options of \`cli seed run\`. */
+export interface SeedRunOptions {
+    /** The stack environment whose \`.starcistacks/<env>/seeds/sql\` runs after \`.starcistacks/seeds/sql\`. */
+    readonly env?: string
+}
 
-@SubCommand({ name: "run", description: "Run the tracked seed through the application role" })
-/** \`cli seed run\`: executes the one tracked seed through the shared least-privilege EntityManager. */
+@SubCommand({ name: "run", description: "Run the tracked SQL seeds through the application role" })
+/** \`cli seed run [--env <name>]\`: executes the shared SQL seeds, then the environment's, through the shared least-privilege EntityManager. */
 export class RunSeedsCli extends CommandRunner {
     constructor(private readonly seeds: SeedRunnerService) {
         super()
     }
 
-    /** Executes the tracked seed when it contains at least one statement. */
-    async run(): Promise<void> {
-        await this.seeds.run()
+    /** \`--env <name>\`: the stack environment whose seed runs after the shared one. */
+    @Option({ flags: "--env <name>", description: "The stack environment whose seed runs", defaultValue: DEFAULT_SEED_ENV })
+    parseEnv(value: string): string {
+        return value
+    }
+
+    /** Executes the shared seed and the environment's own. */
+    async run(_passed: Array<string>, options?: SeedRunOptions): Promise<void> {
+        await this.seeds.run(options?.env)
     }
 }
 `;
@@ -64,17 +76,32 @@ import { Test } from "@nestjs/testing"
 import { SeedRunnerService } from "@modules/platform/database"
 import { RunSeedsCli } from "./run.cli"
 
+const build = async () => {
+    const seeds = mock<SeedRunnerService>()
+    const moduleRef = await Test.createTestingModule({
+        providers: [RunSeedsCli, { provide: SeedRunnerService, useValue: seeds }],
+    }).compile()
+    return { command: moduleRef.get(RunSeedsCli), seeds }
+}
+
 describe("RunSeedsCli", () => {
-    it("delegates the tracked seed run to the seed runner once", async () => {
-        const seeds = mock<SeedRunnerService>()
-        const moduleRef = await Test.createTestingModule({
-            providers: [RunSeedsCli, { provide: SeedRunnerService, useValue: seeds }],
-        }).compile()
+    it("delegates the seed run of the named environment to the seed runner once", async () => {
+        const { command, seeds } = await build()
 
-        await expect(moduleRef.get(RunSeedsCli).run()).resolves.toBeUndefined()
+        await expect(command.run([], { env: "production" })).resolves.toBeUndefined()
 
+        expect(seeds.run).toHaveBeenCalledWith("production")
         expect(seeds.run).toHaveBeenCalledTimes(1)
     })
+
+    it("delegates with no environment when none is named, and takes --env as given", async () => {
+        const { command, seeds } = await build()
+
+        await command.run([])
+
+        expect(seeds.run).toHaveBeenCalledWith(undefined)
+        expect(command.parseEnv("production")).toBe("production")
+    })
 })
 `;
 const SEED_MODULE = `import { Module } from "@nestjs/common"
@@ -82,7 +109,7 @@ import { SeedCli } from "./seed.cli"
 import { RunSeedsCli } from "./subs/run.cli"
 
 @Module({ providers: [SeedCli, RunSeedsCli] })
-/** The lite seed group: the command and its one tracked seed runner. */
+/** The lite seed group: the command and its runner of the tracked SQL seeds. */
 export class SeedModule {}
 `;
 function enableLiteCliDatabase(root) {

package/scaffold/add-module.mjs

@@ -46,10 +46,11 @@ function manifests(project, name, versions) {
         private: true,
         description: `The ${pascalOf(name)} module on the ${project} agent SDK: its template (./template) and workbench declaration (./manifest), both React-free for the back end, its Grammar-only workbench (./workbench) and its public face (./public) for the front end.`,
         exports,
-        scripts: { build: 'tsc -p tsconfig.build.json && tsc -p tsconfig.build.workbench.json', typecheck: 'tsc --noEmit --pretty false', test: 'jest --coverage' },
+        // No test script and no jest config of its own: its specs run in the back end's unit run (the root packages of be/jest.config.js, BE-TEST-13).
+        scripts: { build: 'tsc -p tsconfig.build.json && tsc -p tsconfig.build.workbench.json', typecheck: 'tsc --noEmit --pretty false' },
         dependencies: { [sdk]: '*' },
         peerDependencies: { '@starci/grammar': versions['@starci/grammar'], react: versions['react'] },
-        devDependencies: sortedDependencies({ '@types/jest': versions['@types/jest'] ?? '', '@types/react': versions['@types/react'] ?? '', jest: versions['jest'] ?? '', 'ts-jest': versions['ts-jest'] ?? '', typescript: versions['typescript'] ?? '' }),
+        devDependencies: sortedDependencies({ '@types/jest': versions['@types/jest'] ?? '', '@types/react': versions['@types/react'] ?? '', typescript: versions['typescript'] ?? '' }),
     };
     const build = { rootDir: 'src', noEmit: false, declaration: true, types: [] };
     return [
@@ -65,7 +66,7 @@ function versionsOf(root, feAppFiles) {
     const all = { ...rootPackage.devDependencies, ...rootPackage.dependencies };
     for (const file of feAppFiles)
         Object.assign(all, read(file).dependencies);
-    const wanted = ['@starci/grammar', 'react', '@types/jest', '@types/react', 'jest', 'ts-jest', 'typescript'];
+    const wanted = ['@starci/grammar', 'react', '@types/jest', '@types/react', 'typescript'];
     const missing = wanted.filter((name) => all[name] === undefined);
     if (missing.length > 0)
         throw new ScaffoldError('HFS_ADD_MODULE_PINS', `add module reads the versions of ${missing.join(', ')} from the app's manifests, which declare none of them`);
@@ -117,6 +118,8 @@ function context(root, name) {
     if (!fs.existsSync(declarationFile) || !fs.existsSync(packageFile))
         throw new ScaffoldError('HFS_ADD_NOT_AN_APP', 'a module verb runs at the app root containing hfs.json and package.json');
     const repo = readRepoDeclaration(loadSlotManifest(), root);
+    if (repo.modules === 'data')
+        throw new ScaffoldError('HFS_MODULES_ARE_DATA', 'hfs.json declares modules: "data": a module of this app is a seed under .starcistacks/seeds/data/modules, not a package, so no module verb applies');
     return { project: repo.project, declarationFile, packageFile };
 }
 /** Sets or deletes one dependency of a manifest file, keeping the section sorted; answers whether the text changed. */

package/scaffold/lite-exports.mjs

@@ -173,7 +173,7 @@ const REGISTRATIONS = Object.freeze({
         {
             file: "be/src/modules/platform/database/index.ts",
             source: "./seed-runner.service",
-            names: ["SeedRunnerService"],
+            names: ["DEFAULT_SEED_ENV", "SeedRunnerService"],
             beforeSource: "./database.options",
         },
     ],

package/scaffold/module-registry.mjs

@@ -5,6 +5,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { byCodeUnit } from '../report/order.mjs';
+import { canonImport, canonJson, canonList } from '../sync/canon-layout.mjs';
 import { pascalOf } from './service.mjs';
 /** The folder name prefix of a module package. */
 export const MODULE_PREFIX = 'module-';
@@ -13,7 +14,8 @@ export const REGISTRY_DIR = 'packages/modules';
 /** The product's agent SDK package folder every module builds on. */
 export const SDK_DIR = 'packages/agent-sdk';
 const HEADER = '// Generated by starci app sync (module registry). Do not edit: run "npx starci app sync --execute".';
-const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+// A package.json is printed by Prettier the way JSON.stringify prints it; every other JSON file of the registry follows the canon layout.
+const packageJson = (value) => `${JSON.stringify(value, null, 2)}\n`;
 /** `loyalty-points` as the UPPER_SNAKE prefix of the constants a module exports. */
 export const upperOf = (name) => name.replace(/-/g, '_').toUpperCase();
 /** The module names under `packages/` of the app at `root` (a folder module-<name> holding a package.json), sorted. */
@@ -39,13 +41,13 @@ export function registryFiles(project, names) {
     const sorted = [...names].sort(byCodeUnit);
     const sdk = `@${project}/agent-sdk`;
     const module = (name) => `@${project}/${MODULE_PREFIX}${name}`;
-    const serverImports = sorted.map((name) => `import { ${upperOf(name)}_SERVER } from "${module(name)}/template"`).join('\n');
-    const workbenchImports = sorted.map((name) => `import { ${upperOf(name)}_WORKBENCH } from "${module(name)}/manifest"`).join('\n');
+    const serverImports = sorted.map((name) => canonImport({ names: [`${upperOf(name)}_SERVER`], from: `${module(name)}/template` })).join('\n');
+    const workbenchImports = sorted.map((name) => canonImport({ names: [`${upperOf(name)}_WORKBENCH`], from: `${module(name)}/manifest` })).join('\n');
     const dependencies = Object.fromEntries([[sdk, '*'], ...sorted.map((name) => [module(name), '*'])].sort(([a], [b]) => byCodeUnit(a, b)));
     return [
         {
             path: `${REGISTRY_DIR}/package.json`,
-            content: json({
+            content: packageJson({
                 name: `@${project}/modules`,
                 version: '0.0.0',
                 private: true,
@@ -57,11 +59,11 @@ export function registryFiles(project, names) {
         },
         {
             path: `${REGISTRY_DIR}/tsconfig.json`,
-            content: json({ extends: '@starci/tsconfig/next.json', compilerOptions: { incremental: false, types: [] }, include: ['src/**/*.ts'], exclude: ['node_modules', 'dist'] }),
+            content: canonJson({ extends: '@starci/tsconfig/next.json', compilerOptions: { incremental: false, types: [] }, include: ['src/**/*.ts'], exclude: ['node_modules', 'dist'] }),
         },
         {
             path: `${REGISTRY_DIR}/tsconfig.build.json`,
-            content: json({
+            content: canonJson({
                 extends: './tsconfig.json',
                 compilerOptions: { rootDir: 'src', outDir: 'dist', noEmit: false, declaration: true, module: 'node16', moduleResolution: 'node16' },
             }),
@@ -72,11 +74,11 @@ export function registryFiles(project, names) {
         },
         {
             path: `${REGISTRY_DIR}/src/template/index.ts`,
-            content: `${HEADER}\nimport type { ModuleServer } from "${sdk}/module"\n${serverImports}\n\n/** The server half of every module built on the SDK; the back end reads nothing else of a module. */\nexport const MODULE_SERVERS: ReadonlyArray<ModuleServer> = [${sorted.map((name) => `${upperOf(name)}_SERVER`).join(', ')}]\n`,
+            content: `${HEADER}\n${canonImport({ names: ['ModuleServer'], from: `${sdk}/module`, type: true })}\n${serverImports}\n\n/** The server half of every module built on the SDK; the back end reads nothing else of a module. */\n${canonList({ head: 'export const MODULE_SERVERS: ReadonlyArray<ModuleServer> = ', items: sorted.map((name) => `${upperOf(name)}_SERVER`) })}\n`,
         },
         {
             path: `${REGISTRY_DIR}/src/manifest/index.ts`,
-            content: `${HEADER}\nimport { specRegistryFrom } from "${sdk}/workbench/contract"\nimport type { WorkbenchDeclaration, WorkbenchSpecRegistry } from "${sdk}/workbench/contract"\n${workbenchImports}\n\n/** The workbench declaration of every module built on the SDK; the front end pairs each with how it draws. */\nexport const MODULE_WORKBENCHES: ReadonlyArray<WorkbenchDeclaration> = [${sorted.map((name) => `${upperOf(name)}_WORKBENCH`).join(', ')}]\n\n/** Everything a stored spec may name: the SDK's blocks and each module's exposed blocks, reads and actions. */\nexport const SPEC_REGISTRY: WorkbenchSpecRegistry = specRegistryFrom(MODULE_WORKBENCHES)\n`,
+            content: `${HEADER}\n${canonImport({ names: ['specRegistryFrom'], from: `${sdk}/workbench/contract` })}\n${canonImport({ names: ['WorkbenchDeclaration', 'WorkbenchSpecRegistry'], from: `${sdk}/workbench/contract`, type: true })}\n${workbenchImports}\n\n/** The workbench declaration of every module built on the SDK; the front end pairs each with how it draws. */\n${canonList({ head: 'export const MODULE_WORKBENCHES: ReadonlyArray<WorkbenchDeclaration> = ', items: sorted.map((name) => `${upperOf(name)}_WORKBENCH`) })}\n\n/** Everything a stored spec may name: the SDK's blocks and each module's exposed blocks, reads and actions. */\nexport const SPEC_REGISTRY: WorkbenchSpecRegistry = specRegistryFrom(MODULE_WORKBENCHES)\n`,
         },
     ];
 }

package/src/main.mjs

@@ -8,7 +8,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 // The @starci/hfs implementation behind `starci app`: one repository, `<app>/`, with one package.json, lockfile and node_modules
 // at its root and two sides, be/ and fe/, declared by the one hfs.json of kind app. Every verb runs at the app root.
-//   starci app check [--cwd <dir>] [--json] [--gate <hfs|format|db|secrets|wiring|types|lint|test|sonar|codecov>]... [--side be|fe] [--fix] [--out <sonar file>] [--no-cache] [--coverage-from <lcov>] [--shard <i>/<n>] | check --staged
+//   starci app check [--cwd <dir>] [--json] [--gate <hfs|format|db|secrets|wiring|types|lint|test|sonar|codecov>]... [--side be|fe|packages] [--fix] [--out <sonar file>] [--no-cache] [--coverage-from <lcov>] [--shard <i>/<n>] | check --staged
 //                                            every tracked path has a slot; required files exist; nothing forbidden or
 //                                            tracked-that-must-be-ignored; pins match; every managed file equals its render
 //                                            (sync/managed.mjs, the .gitignore block and sonar-project.properties included); no empty or ghost
@@ -29,7 +29,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 //                                            progress goes to stderr (--quiet silences it). STARCI_APP_CHECK_CACHE=verify runs diff then full and fails (exit 2)
 //                                            on any difference; =full never reads the cache (the release gate).
 //                                            --coverage-from <lcov> judges a coverage report produced elsewhere (the merge of a sharded unit run) and records nothing.
-//                                            --side be|fe limits the lint gate to one side (a CI matrix runs one per side). --out <file> writes every finding of the run as ONE
+//                                            --side be|fe|packages limits the lint gate to one side or to the root packages (a CI matrix runs one per scope). --out <file> writes every finding of the run as ONE
 //                                            Sonar Generic Issue Import document (engine ids starci-hfs, eslint, stylelint). --fix runs ESLint and stylelint with --fix before the
 //                                            check and is refused unless --gate lint is selected.
 //                                            --staged: the pre-commit guard alone (sync/hygiene.mjs: staged .starciwork and .starcistacks paths, the secrets
@@ -104,7 +104,7 @@ import { addKind } from '../scaffold/add.mjs';
 import { removeModule } from '../scaffold/add-module.mjs';
 import { scaffoldApp } from '../scaffold/app.mjs';
 import { newImages } from '../scaffold/image.mjs';
-import { cachedLinters, eslintRepository, runLinter as nativeLinter } from '../lint/run.mjs';
+import { PACKAGES, cachedLinters, eslintRepository, runLinter as nativeLinter } from '../lint/run.mjs';
 import { runSonarForApp, runTestForApp, runTestShard, runTypesForApp } from '../cache/app-families.mjs';
 import { CACHE_ENV, createDiskSession } from '../cache/session.mjs';
 import { DEFAULT_FAMILIES, runAppFamilies } from '../cache/run.mjs';
@@ -177,7 +177,7 @@ const PARSED_FLAGS = new Set([...Object.values(PARSED).flatMap(flagsOf), '--edit
 /** The placeholder of a value flag in the usage; any other prints as <name>. */
 const PLACEHOLDERS = {
     '--gate': `<${CHECK_GATES.join('|')}>`,
-    '--registry-visibility': 'public|private', '--side': 'be|fe', '--edition': 'full|lite', '--base': '<ref>', '--coverage-from': '<lcov>', '--shard': '<i>/<n>', '--inject': '<binding>',
+    '--registry-visibility': 'public|private', '--side': 'be|fe|packages', '--edition': 'full|lite', '--base': '<ref>', '--coverage-from': '<lcov>', '--shard': '<i>/<n>', '--inject': '<binding>',
     '--event': '<event>', '--from': '<service>', '--service': '<Class>=<module>', '--owner': '<service>', '--failed': '<event>', '--done': '<event>',
     '--shapes': '<a,b,c>', '--blocks': '<a,b>', '--tabs': '<a,b>', '--kind': 'modal|drawer', '--image': '<service>=<ref>', '--sha': '<sha>',
     '--previous': '<release>', '--release': '<release>', '--out': '<path>', '--since': '<ISO>', '--timeout': '<seconds>', '--retry': '<seconds>',
@@ -478,7 +478,7 @@ function familyOf(finding) {
 async function fixLint({ repoRoot, side, run }) {
     const app = readRepoDeclaration(loadSlotManifest(), repoRoot);
     await eslintRepository({ repoRoot, app, opts: { ...(side === undefined ? {} : { side }), fix: true }, run });
-    if (side !== 'be')
+    if (side === undefined || side === 'fe')
         await (run ?? nativeLinter)({ cwd: path.join(repoRoot, 'fe'), pkg: 'stylelint', bin: 'stylelint', args: [STYLE_GLOB, '--formatter', 'json', '--fix'] });
 }
 /** One run of the selected families against the cache, then the coverage proof on top; returns the result, what it took and the raw linter results. */
@@ -543,7 +543,7 @@ function writeSonarImport({ repoRoot, file, findings, raw, side }) {
     const onSide = (candidate) => {
         if (side === undefined)
             return true;
-        const owner = SIDES.find((each) => candidate === each || candidate.startsWith(`${each}/`));
+        const owner = [...SIDES, PACKAGES].find((each) => candidate === each || candidate.startsWith(`${each}/`));
         return (owner ?? 'be') === side;
     };
     const sourceRoots = sourceRootsOf(properties).filter(onSide);
@@ -591,8 +591,8 @@ async function checkMain(opts, io) {
     const sonarOut = valueFlag(opts, 'out');
     const fix = booleanFlag(opts, 'fix') === true;
     const explicit = selectedFamilies(opts, []);
-    if (side !== undefined && !['be', 'fe'].includes(side))
-        throw new UsageError('LINT_SIDE_INVALID: --side is be or fe');
+    if (side !== undefined && !['be', 'fe', PACKAGES].includes(side))
+        throw new UsageError('LINT_SIDE_INVALID: --side is be, fe or packages');
     if (fix && !explicit.has('lint'))
         throw new UsageError('--fix runs the linters and needs --gate lint');
     if (shard !== undefined) {