@starci/hfs 5.3.0 → 5.5.0

package/runtime/scripts/hfs/rules/stacks.mjs

@@ -1,7 +1,7 @@
 // stacks.mjs - HFS_STACKS_SHAPE (R10): standard stack shape, Sonar owner and deployment runtime consistency.
 //   - every tracked path under the app root's `.starcistacks/` is one the app.starcistacks slot allows (its `allows` list is the shape:
 //     application-stacks.yaml and <env>/{README.md, environment.json, infra/{compose,swarm,k8s,terraform}, runtime/{config,env},
-//     secrets/<slug>.enc.yaml, seeds}); a `.enc` outside <env>/secrets/ is never allowed, `runtime/files/`, a root `DESIGN.md`,
+//     secrets/<slug>.enc.yaml}, and the seed levels seeds/ and <env>/seeds/); a `.enc` outside <env>/secrets/ is never allowed, `runtime/files/`, a root `DESIGN.md`,
 //     `deployment.json` and `k8s/` are not in the list, so they fall out of it;
 //   - the declaration (read by scripts/lib/stack-declaration.mjs, the one reader of it) states a sonar service, a local
 //     Sonar is owned by the host (`stack.owner: host`, root `.claude/ext/sonar`).
@@ -15,6 +15,8 @@ const STACKS_SHAPE = 'HFS_STACKS_SHAPE';
 const STACKS_SLOT = 'app.starcistacks';
 const HOST_SONAR_ROOT = '.claude/ext/sonar';
 const INSIDE_SECRETS = /^[^/]+\/secrets\/[^/]+\.enc(?:\.yaml)?$/;
+/** The folders of .starcistacks/ that are no environment, each with what it holds. */
+const RESERVED = [['cache', 'the committed check cache'], ['seeds', 'the shared seed level']];
 /** The anchored expressions of a slot's `allows` entries: `<name>` is one path segment, braces alternate. */
 const allowedExpressions = (allows) => allows.flatMap((entry) => braceVariants(entry.replace(/<[a-z][a-z0-9-]*>/g, '*'))).map((variant) => globExpression(variant.endsWith('/') ? `${variant}**` : variant));
 const shapeFinding = (file, message, extra) => found(STACKS_SHAPE, file, message, extra);
@@ -26,7 +28,7 @@ function treeFindings(files, allowed, prefix) {
         if (/\.enc(?:\.yaml)?$/.test(rel) && !INSIDE_SECRETS.test(rel))
             findings.push(shapeFinding(file, `${file} is a sealed secret outside <env>/secrets/<slug>.enc.yaml; move it to .starcistacks/<env>/secrets/`));
         else if (!allowed.some((expression) => expression.test(rel)))
-            findings.push(shapeFinding(file, `${file} is not part of the standard .starcistacks shape (application-stacks.yaml, images/db/Dockerfile in lite and <env>/{README.md, environment.json, infra, runtime/{config,env}, secrets/<slug>.enc.yaml, seeds}); move or delete it`));
+            findings.push(shapeFinding(file, `${file} is not part of the standard .starcistacks shape (application-stacks.yaml, images/db/Dockerfile in lite and <env>/{README.md, environment.json, infra, runtime/{config,env}, secrets/<slug>.enc.yaml}, and the seed levels seeds/ and <env>/seeds/ with their seeds.yaml, sql/, data/ and files/); move or delete it`));
     }
     return findings;
 }
@@ -36,8 +38,10 @@ function declarationFindings(files, prefix, declaration) {
         return [];
     const findings = [];
     const environments = declaration.doc?.environments;
-    if (environments !== null && typeof environments === 'object' && Object.hasOwn(environments, 'cache'))
-        findings.push(shapeFinding(declared, `${declared} declares an environment named cache; the name is reserved for the committed check cache (.starcistacks/cache/)`));
+    for (const [name, holds] of RESERVED) {
+        if (environments !== null && typeof environments === 'object' && Object.hasOwn(environments, name))
+            findings.push(shapeFinding(declared, `${declared} declares an environment named ${name}; the name is reserved for ${holds} (.starcistacks/${name}/)`));
+    }
     if (declaration.error)
         return [shapeFinding(declared, `${declared} cannot be read: ${declaration.error}`)];
     const services = declaration.doc?.services;

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

@@ -34,6 +34,8 @@ export interface RepoView {
     profile: string;
     apps: readonly AppRef[];
     optionalSlots: readonly string[];
+    /** How the app keeps its agent modules (app view only): `packages` (module packages and the rendered registry) unless hfs.json declares `modules: "data"`. */
+    modules?: 'packages' | 'data';
     patterns?: readonly string[];
     kinds?: readonly string[];
     backing?: readonly string[];

package/runtime/scripts/hfs/slots.mjs

@@ -177,6 +177,7 @@ export function resolveRepoDeclaration(manifest, declaration, { file = HFS_DECLA
         // tsconfig.json that type-checks it, both switched on by `browser: true`.
         apps: Object.freeze([]),
         optionalSlots: Object.freeze(declaration.browser === true ? ['app.browser', 'app.browser-config'] : []),
+        modules: declaration.modules === 'data' ? 'data' : 'packages',
         connections: Object.freeze([]),
         providers,
         reads: Object.freeze([]),

package/runtime/scripts/hfs/stack-seeds-config.d.mts

@@ -0,0 +1,88 @@
+import type { StackProblem } from './stack-config-kit.mjs';
+export declare const SEEDS_SCHEMA = "starci/seeds@1";
+/** The folder name of a seed level, at `.starcistacks/` and under each environment. */
+export declare const SEEDS_DIR = "seeds";
+/** The manifest of a level. */
+export declare const SEEDS_MANIFEST = "seeds.yaml";
+/** The kinds of entry; each lives in the folder `kindFolder` names. */
+export declare const SEED_KINDS: readonly ["sql", "data", "test-account", "files"];
+/** The folders of a level. */
+export declare const SEED_FOLDERS: readonly ["sql", "data", "files"];
+/** `once`: applied a single time; `upsert`: applied again whenever its content hash changes. */
+export declare const SEED_MODES: readonly ["once", "upsert"];
+/** The placeholder that keeps an empty seed folder tracked. */
+export declare const SEEDS_KEEP = ".gitkeep";
+/** The kind of one entry. */
+export type SeedKind = (typeof SEED_KINDS)[number];
+/** One entry of a level's manifest, normalised; `target` is the database (`sql`), the app command argv (`data`, `test-account`) or the bucket (`files`). */
+export interface SeedEntry {
+    id: string;
+    kind: SeedKind;
+    path: string;
+    target: string | string[];
+    mode: (typeof SEED_MODES)[number];
+    after: string[];
+    schema: string | null;
+    reason: string | null;
+}
+/** One document of a data or test-account entry, level-relative, parsed or with the reason it does not parse. */
+export type SeedDocument = {
+    path: string;
+    doc: unknown;
+    error?: undefined;
+} | {
+    path: string;
+    error: string;
+    doc?: undefined;
+};
+/** A level as the check and the seed step see it: its app-relative folder, its entries in apply order and its problems. */
+export interface SeedLevel {
+    dir: string;
+    env: string | null;
+    entries: SeedEntry[];
+    problems: StackProblem[];
+}
+/** The name of a sealed member a seed document may reference. */
+export declare const SEED_SECRET_MEMBER: RegExp;
+/** The folder of a level a kind's paths live in: a test account is data. */
+export declare const kindFolder: (kind: SeedKind) => (typeof SEED_FOLDERS)[number];
+/** True for an entry the app command loads as documents: `data` and `test-account`. */
+export declare const isDocumentEntry: (entry: Pick<SeedEntry, "kind">) => boolean;
+/** The sealed member file of `member` in the environment `env`, app-relative. */
+export declare const seedMemberFile: (env: string, member: string) => string;
+/** The app-relative folder of a level: the shared one when `env` is null. */
+export declare const seedLevelDir: (env: string | null) => string;
+/** Every file under `folder` (absolute) as a path relative to `base`, posix and sorted, the placeholders aside; a missing folder holds none. */
+export declare function filesBelow(base: string, folder: string): string[];
+/** The level-relative files an entry covers: its path when it is a file, every file below it when it is a folder. */
+export declare function entryFiles(levelRoot: string, entry: Pick<SeedEntry, 'path'>): string[];
+/** The content hash of an entry: its kind, target, mode and every file it covers, by path and bytes. */
+export declare function entryDigest(levelRoot: string, entry: SeedEntry): string;
+/**
+ * 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 declare function normalizeSeeds(doc: unknown, levelRoot: string, shared?: ReadonlySet<string> | null): {
+    entries: SeedEntry[];
+    problems: StackProblem[];
+};
+/** Reads and judges the level of `env` (null: the shared level) at `repoRoot`; a level without a manifest has no entries. */
+export declare function readSeedLevel(repoRoot: string, env: string | null, shared?: ReadonlySet<string>): SeedLevel;
+/** The documents of a data or test-account entry: every JSON or YAML file it covers, parsed. */
+export declare function seedDocuments(levelRoot: string, entry: Pick<SeedEntry, 'path'>): SeedDocument[];
+/** The member a value references when it is a secret reference (`{ "secret": "<member>" }` and nothing else), else null. */
+export declare function secretReference(value: unknown): string | null;
+/** Every member the secret references of a document name, in document order, once each. */
+export declare function secretReferences(doc: unknown): string[];
+/** A copy of `doc` with every secret reference replaced by what `resolve` answers for its member. */
+export declare function resolveSecrets(doc: unknown, resolve: (member: string) => unknown): unknown;
+/** An entry to declare in a manifest: `after` and `schema` as the manifest spells them, left out when empty. */
+export type SeedEntryInput = Pick<SeedEntry, 'id' | 'kind' | 'path' | 'target' | 'mode'> & {
+    after?: string[];
+    schema?: string;
+};
+/**
+ * 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 declare function addSeedEntries(repoRoot: string, env: string | null, entries: SeedEntryInput[], write?: boolean): string[];

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. */