@starci/hfs 5.4.0 → 5.5.0

package/stack/deploy.d.mts

@@ -1,5 +1,6 @@
 import type { DeployConfig } from './config.mjs';
 import type { StackContext } from './context.mjs';
+import type { DeployDatabase } from './db-phases.mjs';
 import type { ProvisionOptions } from './provision.mjs';
 import type { ObservedService } from './status.mjs';
 import type { ActionResult, Runner, SshOptions } from './remote.mjs';
@@ -62,6 +63,8 @@ export interface DeployDeps {
     }) => Promise<ActionResult>;
     reconcileEdge: (ctx: StackContext, config: DeployConfig, file: string) => ActionResult | Promise<ActionResult>;
     postDeployStack: (ctx: StackContext, config: DeployConfig) => Promise<ActionResult>;
+    /** The seed step after convergence (seeds.mjs seedDeployed). */
+    seedRelease: (ctx: StackContext, config: DeployConfig, database: DeployDatabase, f: FloorDeps) => Promise<ActionResult>;
     verifyStack: (ctx: StackContext, config: DeployConfig, options: {
         retrySeconds?: number | undefined;
         skipPublic?: boolean;

package/stack/deploy.mjs

@@ -35,6 +35,7 @@ import { describeClash, edgeCollisions, reconcileEdgeAliases } from './edge-alia
 import { firstLine, tool } from './context.mjs';
 import { hasPlaceholderDigest, isReleaseId } from './digest.mjs';
 import { contractPhase, declaredDatabase, expandPhase, firstStartHooks, FLOOR_DEPS, unknownDatabaseService } from './db-phases.mjs';
+import { hasSeedEntries, seedPlanLine } from './seeds.mjs';
 import { failure, refusal } from './errors.mjs';
 import { recordedAttempt } from './journal.mjs';
 import { postDeployStack } from './post-deploy.mjs';
@@ -57,6 +58,7 @@ export const DEFAULT_DEPS = Object.freeze({
     convergeStack,
     reconcileEdge: reconcileEdgeAliases,
     postDeployStack,
+    seedRelease: lazy('./seeds.mjs', 'seedDeployed'),
     verifyStack,
     pruneStack,
     releaseStore: createReleaseStore,
@@ -340,6 +342,7 @@ async function deployExecute(ctx, config, options, d, out, seams) {
         ['deploy', () => stackDeploy(ctx, config, stackFile)],
         ['edge', async () => d.reconcileEdge(ctx, config, stackFile)],
         ['converge', async () => { const converged = await d.convergeStack(ctx, config, { since, timeoutSeconds: options.timeoutSeconds }); snapshot(ctx, config, d, rec, 'converge'); return converged; }],
+        ...(database && hasSeedEntries(config.repoRoot, config.env) ? [['seed', () => d.seedRelease(ctx, config, database, { ...FLOOR_DEPS, ...d.floor })]] : []),
         ...(config.postDeploy.length > 0 ? [['post-deploy', () => d.postDeployStack(ctx, config)]] : []),
         ['verify', () => d.verifyStack(ctx, config, { retrySeconds: options.retrySeconds, skipPublic: skipPublic === true, stackFile: path.join(out, 'stack.yaml') })],
         ...(skipPublic ? [] : [['accept', async () => { await acceptObserved(ctx, config, d, store, rec, { out, releaseId }); return { ok: true, lines: [`accepted release ${releaseId}`] }; }]]),
@@ -400,7 +403,7 @@ export async function deployRelease(ctx, config, options = {}, deps = {}) {
             const { rendered, releaseId } = await render();
             const post = config.postDeploy.length > 0 ? ` post-deploy tasks (${config.postDeploy.join(', ')}),` : '';
             const database = options.urgent === true ? null : await declaredDatabase(ctx, config);
-            const databasePlan = database ? `; database (${database.target === 'stack' ? `inside the ${database.service} container, no URL held` : 'external, by --db-url-env'}): migrate preview, a verified backup only when a migration is pending, the expand migrations before the deploy, the contract migrations after the accept, and an automatic first start when no release was ever accepted` : '';
+            const databasePlan = database ? `; database (${database.target === 'stack' ? `inside the ${database.service} container, no URL held` : 'external, by --db-url-env'}): migrate preview, a verified backup only when a migration is pending, the expand migrations before the deploy, the contract migrations after the accept, and an automatic first start when no release was ever accepted${hasSeedEntries(config.repoRoot, config.env) ? `; ${seedPlanLine(config.repoRoot, config.env)}` : ''}` : '';
             const plan = options.skipPublic
                 ? `dry run: release ${releaseId} would be provisioned, stored, pre-pulled, deployed, converged,${post} and verified inside the stack (public hosts skipped); it would stay pending until ingress publish and stack accept${databasePlan}`
                 : `dry run: release ${releaseId} would be provisioned, stored, pre-pulled, deployed, converged,${post} verified, accepted${databasePlan}`;

package/stack/local-up.mjs

@@ -1,16 +1,19 @@
 // local-up.mjs - `starci app stack up --env <dev env> [--execute]`: the one command that brings the whole dev environment up (PROJECT-STACKS-6).
 // Order: host prerequisites, dev custody, setup (install, codegen), compose services and their health, the environment's own database role,
-// migrations with a receipt, seed, native app processes, readiness, origins. Idempotent: what runs is kept, what changed is converged.
+// migrations with a receipt, the seed levels with their receipts, the seed commands, native app processes, readiness, origins. Idempotent: what runs is kept, what changed is converged.
 // A dry run prints the plan. It never generates a replacement secret, never removes a volume and touches only its own compose project.
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { firstLine } from './context.mjs';
+import { dbTarget } from '../db/postgres.mjs';
 import { failure, refusal } from './errors.mjs';
 import { missingKeys, missingStep, openCustody } from './local-custody.mjs';
 import { hostRefusal, preflight, runSetup } from './local-prepare.mjs';
 import { DEFAULT_TIMEOUT_SECONDS, makeDataDirectories, commandDigest, compose, composeValues, databaseUrl, isAlive, probe, runCommand, runEnvironment, serviceReady, startProcess, stateOf, waitFor } from './local-run.mjs';
+import { launch } from './local-host.mjs';
 import { readRecord, writeRecord } from './local-state.mjs';
+import { SEED_RECEIPTS, seedStep } from './seeds.mjs';
 import { ensureRuntimeLayers, layerPlan } from './runtime-layers.mjs';
 const SAFE_PASSWORD = /^[A-Za-z0-9_-]{8,}$/u;
 /** The digest of the migration folder (names and contents): what a migrate receipt records. */
@@ -81,6 +84,25 @@ async function migrate(ctx, local, custody, deps) {
     writeRecord(dir, record);
     return `migrate: applied, receipt ${record.receipts.migrate.digest}${await appRolePassword(ctx, local, custody)}`;
 }
+/**
+ * Applies the seed levels (seeds.mjs, PROJECT-STACKS-12) on the environment's database under its owner role, the role the migrations ran as: the
+ * receipts in the database keep a rerun from applying anything that did not change. A document entry's app command runs from the app root with
+ * the owner's environment, the documents on its stdin.
+ */
+async function seedLevels(ctx, local, custody) {
+    const database = local.database;
+    const url = databaseUrl(local, custody);
+    if (!database || url === null)
+        return [];
+    const container = firstLine((await compose(ctx, local, ['ps', '-q', database.service])).stdout);
+    const target = dbTarget({ ...ctx, env: { ...ctx.env, DATABASE_URL: url, STARCI_DB_CONTAINER: container } }, 'DATABASE_URL');
+    const env = runEnvironment(ctx, local, { name: 'seed', argv: [], cwd: '.', heavy: 'none', skipIfExists: null, env: {}, files: [...custody.values.keys()], after: 'migrate' }, custody, 'owner');
+    const command = (argv, input) => {
+        const [program, args] = launch(ctx.platform, argv[0] ?? '', argv.slice(1));
+        return ctx.spawn(program, args, { cwd: local.repoRoot, env, input });
+    };
+    return seedStep({ ctx, repoRoot: local.repoRoot, env: local.env, target, execute: true, command }).lines;
+}
 /** Runs the seed commands once each (a receipt keyed by the command's digest); the seed owns its idempotence beyond that. */
 async function seed(ctx, local, custody, after) {
     const dir = stateOf(ctx, local);
@@ -125,7 +147,7 @@ function plan(local, missing) {
         ...local.setup.map((run) => `plan setup ${run.name}: ${run.argv.join(' ')}`),
         ...layerPlan(local),
         `plan services: ${local.services.map((service) => `${service.name} (wait ${service.wait})`).join(', ')}`,
-        ...(local.database ? [`plan database: own role ${local.database.role}, database ${local.database.name}, then starci app db migrate`] : []),
+        ...(local.database ? [`plan database: own role ${local.database.role}, database ${local.database.name}, then starci app db migrate`, `plan seed levels: .starcistacks/seeds, then .starcistacks/${local.env}/seeds, each entry once per content hash (receipts in ${SEED_RECEIPTS})`] : []),
         ...local.seed.map((run) => `plan seed ${run.name}: ${run.argv.join(' ')}`),
         ...local.processes.map((run) => `plan process ${run.name}: ${run.argv.join(' ')}`),
         ...local.ready.map((row) => `plan ready ${row.name}: ${row.url}`),
@@ -156,7 +178,7 @@ export async function upLocal(ctx, local, { execute = false, timeoutSeconds = DE
         if (!ready.ok)
             throw failure('STACK_LOCAL_SERVICE', `${service.name} did not become ready in ${timeoutSeconds}s (${ready.detail}); read it with: starci app stack logs --env ${local.env} --service ${service.name}`);
     }
-    lines.push(await provisionDatabase(ctx, local, custody), await migrate(ctx, local, custody, deps), ...await seed(ctx, local, custody, 'migrate'), ...startProcesses(ctx, local, custody, deps));
+    lines.push(await provisionDatabase(ctx, local, custody), await migrate(ctx, local, custody, deps), ...await seedLevels(ctx, local, custody), ...await seed(ctx, local, custody, 'migrate'), ...startProcesses(ctx, local, custody, deps));
     for (const row of local.ready) {
         const result = await waitFor(ctx, deadline, () => probe(ctx, local, row));
         lines.push(`${result.ok ? 'ok    ' : 'FAIL  '}ready ${result.detail}`);

package/stack/seeds.d.mts

@@ -0,0 +1,29 @@
+import type { DbTarget } from '../db/postgres.mjs';
+import type { DeployConfig } from './config.mjs';
+import type { RunResult, StackContext } from './context.mjs';
+import type { DeployDatabase, FloorDeps } from './db-phases.mjs';
+import type { ActionResult } from './remote.mjs';
+/** The receipts table of the seed step, in the app's database. */
+export declare const SEED_RECEIPTS = "public.starci_seed_receipts";
+/** What the seed step reaches: the app root, the environment, its database (the migrations' target) and how an app command runs. */
+export interface SeedStepInput {
+    ctx: StackContext;
+    repoRoot: string;
+    env: string;
+    target: DbTarget;
+    execute: boolean;
+    /** Runs a document entry's app command with the resolved documents on stdin. */
+    command: (argv: readonly string[], input: string) => RunResult;
+}
+/** The seed step of `env`: plans it, or with `execute` applies it. Returns { ok, lines, data: { applied, kept } }. */
+export declare function seedStep(input: SeedStepInput): ActionResult;
+/** True when either seed level of the environment declares an entry. */
+export declare function hasSeedEntries(repoRoot: string, env: string): boolean;
+/** What a deploy's dry run says of the seed step: every entry of the two levels, each applied unless its receipt holds. */
+export declare function seedPlanLine(repoRoot: string, env: string): string;
+/**
+ * The seed step of a deploy (PROJECT-STACKS-6), after convergence so a document entry's app command is the new release's: in the database
+ * container under the credentials it holds (the role the migrations ran as), each app command inside a running task of the jobs service
+ * (`deploy.jobs.service`), the documents on its stdin.
+ */
+export declare function seedDeployed(ctx: StackContext, config: DeployConfig, database: Pick<DeployDatabase, 'service'>, f: Pick<FloorDeps, 'dbContainer' | 'containerTarget'>): Promise<ActionResult>;

package/stack/seeds.mjs

@@ -0,0 +1,197 @@
+// seeds.mjs - the seed step (contexts/project/stacks.md PROJECT-STACKS-12): after the migrations, the entries of the shared level and then of
+// the environment's level, each in apply order, on the database the migrations ran on and under the role they ran as. The harness owns
+// the receipts: one row per entry in `public.starci_seed_receipts` of that database, created by this step (never an app migration), holding
+// the entry's content hash and, for a document entry with secret references, the member names and a digest of their values. A `once` entry
+// with a receipt never runs again; an `upsert` entry runs again when its hash (or a referenced secret) changed; a rerun with nothing changed
+// writes nothing. A `sql` entry runs in one transaction with its receipt. A `data` or `test-account` entry validates its documents against the
+// app's schema, opens their secret references in memory with the environment's age identity (the sops seam) and hands the resolved documents
+// to the app command it names on stdin, never in argv, a file or a log; its receipt is written once the command succeeded. A `files` entry
+// is validated only: the harness has no object-storage client, so its upload stays the app's. Without `execute` the step reads the
+// receipts and prints what would apply.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { literal, psqlTransaction, queryRows } from '../db/postgres.mjs';
+import { validateAgainstSchema } from '../runtime/scripts/lib/json-schema.mjs';
+import { parseYaml } from '../runtime/engine/yaml.mjs';
+import { envelopeOf } from '../runtime/scripts/hfs/secret-document.mjs';
+import { entryDigest, entryFiles, isDocumentEntry, readSeedLevel, resolveSecrets, secretReferences, seedDocuments, seedMemberFile } from '../runtime/scripts/hfs/stack-seeds-config.mjs';
+import { lines as splitLines, tool } from './context.mjs';
+import { DB_WAIT_SECONDS } from './db-phases.mjs';
+import { failure, refusal } from './errors.mjs';
+/** The receipts table of the seed step, in the app's database. */
+export const SEED_RECEIPTS = 'public.starci_seed_receipts';
+const RECEIPTS_DDL = `create table if not exists ${SEED_RECEIPTS} (scope text not null, id text not null, hash text not null, secrets text not null default '', env text not null, applied_at timestamptz not null default now(), primary key (scope, id))`;
+/** The scope of the shared level's receipts; an environment's level uses its name. */
+const SHARED_SCOPE = 'shared';
+/** What a secret's value reads as in a dry run, which opens no member. */
+const SEALED = '[sealed]';
+const sha = (text) => crypto.createHash('sha256').update(text).digest('hex');
+/** The two levels of `env` in apply order; a manifest problem refuses the step before anything runs. */
+function levelsOf(repoRoot, env) {
+    const shared = readSeedLevel(repoRoot, null);
+    const own = readSeedLevel(repoRoot, env, new Set(shared.entries.map((entry) => entry.id)));
+    for (const level of [shared, own]) {
+        const [problem] = level.problems;
+        if (problem)
+            throw refusal('STACK_SEED_MANIFEST', `${level.dir}/seeds.yaml ${problem.at}: ${problem.message}; run starci app check`);
+    }
+    return [shared, own];
+}
+/** The receipts the database holds; none before the first armed run created the table. */
+function receiptsOf(input) {
+    const [present] = queryRows(input.ctx, input.target, `select to_regclass(${literal(SEED_RECEIPTS)}) is not null as present`);
+    if (present?.present !== true)
+        return [];
+    return queryRows(input.ctx, input.target, `select scope, id, hash, secrets from ${SEED_RECEIPTS}`).map((row) => ({ scope: String(row.scope), id: String(row.id), hash: String(row.hash), secrets: String(row.secrets) }));
+}
+/** The statement that records an entry's receipt. */
+const receiptSql = (item, env, secrets) => `insert into ${SEED_RECEIPTS} (scope, id, hash, secrets, env) values (${literal(item.scope)}, ${literal(item.entry.id)}, ${literal(item.hash)}, ${literal(secrets)}, ${literal(env)}) ` +
+    'on conflict (scope, id) do update set hash = excluded.hash, secrets = excluded.secrets, env = excluded.env, applied_at = now()';
+/** The documents of a document entry with its secret references resolved by `open`, refused when one fails the app's schema. */
+function resolvedDocuments(input, item, open) {
+    const schemaText = fs.readFileSync(path.join(input.repoRoot, String(item.entry.schema)), 'utf8');
+    const schema = item.entry.schema?.endsWith('.json') ? JSON.parse(schemaText) : parseYaml(schemaText);
+    return seedDocuments(path.join(input.repoRoot, item.level.dir), item.entry).map((document) => {
+        if (document.error !== undefined)
+            throw refusal('STACK_SEED_DATA_INVALID', `${item.scope}/${item.entry.id}: ${document.path} does not parse`);
+        const resolved = resolveSecrets(document.doc, open);
+        const [error] = validateAgainstSchema(resolved, schema);
+        if (error !== undefined)
+            throw refusal('STACK_SEED_DATA_INVALID', `${item.scope}/${item.entry.id}: ${document.path} does not validate against ${String(item.entry.schema)}: ${error.replace(/:.*$/u, '')}`);
+        return { path: document.path, document: resolved };
+    });
+}
+/** The members a document entry references, in first-use order. */
+const membersOf = (input, item) => [...new Set(seedDocuments(path.join(input.repoRoot, item.level.dir), item.entry).flatMap((document) => secretReferences(document.doc)))];
+/** Opens one sealed member of the environment in memory (the sops seam and its age identity) and answers its map. */
+function openMember(input, member) {
+    const file = memberPath(input, member);
+    return input.ctx.sops.decrypt(file, envelopeOf(fs.readFileSync(file, 'utf8')).format);
+}
+/** The sealed file of a member of the environment; refused when the environment does not seal it. */
+function memberPath(input, member) {
+    const file = path.join(input.repoRoot, seedMemberFile(input.env, member));
+    if (!fs.existsSync(file))
+        throw refusal('STACK_SEED_SECRET_MISSING', `${seedMemberFile(input.env, member)} is not sealed; seal it with starci app secret set --env ${input.env}`);
+    return file;
+}
+/** What a member reads as in a dry run: its key names from the envelope, each a sealed placeholder; no value is opened. */
+function sealedMember(input, member) {
+    return Object.fromEntries(envelopeOf(fs.readFileSync(memberPath(input, member), 'utf8')).keys.map((key) => [key, SEALED]));
+}
+/** The receipt text of the opened members: each name with a digest of its values, never a value. */
+const secretsReceipt = (opened) => [...opened].map(([member, values]) => `${member}:${sha(JSON.stringify(Object.entries(values).sort(([a], [b]) => (a < b ? -1 : Number(a > b))))).slice(0, 16)}`).join(',');
+/** Applies one document entry: the app command with the resolved documents on stdin, then its receipt; answers the receipt's secrets. */
+function applyDocuments(input, item, receipt) {
+    const opened = new Map();
+    const open = (member) => {
+        const known = opened.get(member);
+        if (known)
+            return known;
+        const values = openMember(input, member);
+        opened.set(member, values);
+        return values;
+    };
+    const documents = resolvedDocuments(input, item, open);
+    const secrets = secretsReceipt(opened);
+    if (receipt?.hash === item.hash && receipt.secrets === secrets)
+        return null;
+    const run = input.command(item.entry.target, `${JSON.stringify({ env: input.env, scope: item.scope, entry: item.entry.id, kind: item.entry.kind, documents })}\n`);
+    if (run.error || run.status !== 0)
+        throw failure('STACK_SEED_COMMAND', `${item.scope}/${item.entry.id}: ${item.entry.target.join(' ')} ${run.error ? 'could not run' : `exited ${String(run.status)}`}; its output is withheld (it held the opened secrets)`);
+    psqlTransaction(input.ctx, input.target, [{ sql: receiptSql(item, input.env, secrets) }], { withhold: true, code: 'STACK_SEED_RECEIPT' });
+    return secrets;
+}
+/** The line of an entry the step leaves as it is, or null when it applies. */
+function keptLine(item, receipt) {
+    const name = `seed ${item.scope}/${item.entry.id}`;
+    if (item.entry.kind === 'files')
+        return `${name}: validated, not uploaded (files: the harness has no object-storage client; the app uploads them to ${String(item.entry.target)})`;
+    if (receipt && item.entry.mode === 'once')
+        return `${name}: kept (once, applied before)`;
+    if (receipt?.hash === item.hash && item.entry.kind === 'sql')
+        return `${name}: unchanged (upsert)`;
+    return null;
+}
+/** The seed step of `env`: plans it, or with `execute` applies it. Returns { ok, lines, data: { applied, kept } }. */
+export function seedStep(input) {
+    const planned = levelsOf(input.repoRoot, input.env).flatMap((level) => level.entries.map((entry) => ({
+        level, scope: level.env ?? SHARED_SCOPE, entry, hash: entryDigest(path.join(input.repoRoot, level.dir), entry),
+    })));
+    if (planned.length === 0)
+        return { ok: true, lines: ['seed: no entry in .starcistacks/seeds or the level of the environment'], data: { applied: [], entries: 0 } };
+    const receipts = receiptsOf(input);
+    const lines = [];
+    const applied = [];
+    if (input.execute)
+        psqlTransaction(input.ctx, input.target, [{ sql: RECEIPTS_DDL }], { code: 'STACK_SEED_RECEIPT' });
+    for (const item of planned) {
+        const receipt = receipts.find((row) => row.scope === item.scope && row.id === item.entry.id);
+        const kept = keptLine(item, receipt);
+        const name = `${item.scope}/${item.entry.id}`;
+        if (kept !== null) {
+            lines.push(kept);
+            continue;
+        }
+        if (!input.execute) {
+            const members = isDocumentEntry(item.entry) ? membersOf(input, item) : [];
+            if (isDocumentEntry(item.entry))
+                resolvedDocuments(input, item, (member) => sealedMember(input, member));
+            const unchanged = receipt?.hash === item.hash;
+            lines.push(`plan seed ${name}: ${unchanged ? 'apply when a referenced secret changed' : 'apply'} (${item.entry.kind}, ${item.entry.mode}${members.length ? `, secrets ${members.join(', ')}` : ''})`);
+            continue;
+        }
+        if (item.entry.kind === 'sql') {
+            const files = entryFiles(path.join(input.repoRoot, item.level.dir), item.entry).map((file) => ({ file: path.join(input.repoRoot, item.level.dir, file) }));
+            psqlTransaction(input.ctx, input.target, [...files, { sql: receiptSql(item, input.env, '') }], { code: 'STACK_SEED_SQL' });
+            lines.push(`seed ${name}: applied (sql, ${item.entry.mode}, ${files.length} file${files.length === 1 ? '' : 's'})`);
+            applied.push(name);
+            continue;
+        }
+        const secrets = applyDocuments(input, item, receipt);
+        if (secrets === null) {
+            lines.push(`seed ${name}: unchanged (${item.entry.mode})`);
+            continue;
+        }
+        lines.push(`seed ${name}: applied (${item.entry.kind}, ${item.entry.mode}${secrets ? `, secrets ${secrets.split(',').map((part) => part.split(':')[0]).join(', ')}` : ''})`);
+        applied.push(name);
+    }
+    if (planned.length === 0)
+        lines.push('seed: no entry in .starcistacks/seeds or the environment\'s level');
+    return { ok: true, lines, data: { applied, entries: planned.length } };
+}
+/** The running container of a service of the stack on this daemon, or undefined. */
+function serviceContainer(ctx, config, service) {
+    const found = tool(ctx, 'docker', ['ps', '-q', '--filter', `label=com.docker.swarm.service.name=${config.stack}_${service}`, '--filter', 'status=running']);
+    return splitLines(found.stdout)[0];
+}
+/** True when either seed level of the environment declares an entry. */
+export function hasSeedEntries(repoRoot, env) {
+    return readSeedLevel(repoRoot, null).entries.length > 0 || readSeedLevel(repoRoot, env).entries.length > 0;
+}
+/** What a deploy's dry run says of the seed step: every entry of the two levels, each applied unless its receipt holds. */
+export function seedPlanLine(repoRoot, env) {
+    const entries = levelsOf(repoRoot, env).flatMap((level) => level.entries.map((entry) => `${level.env ?? SHARED_SCOPE}/${entry.id} (${entry.kind}, ${entry.mode})`));
+    return `seed after convergence, each entry unless its receipt in ${SEED_RECEIPTS} holds: ${entries.join(', ')}`;
+}
+/**
+ * The seed step of a deploy (PROJECT-STACKS-6), after convergence so a document entry's app command is the new release's: in the database
+ * container under the credentials it holds (the role the migrations ran as), each app command inside a running task of the jobs service
+ * (`deploy.jobs.service`), the documents on its stdin.
+ */
+export async function seedDeployed(ctx, config, database, f) {
+    const container = await f.dbContainer(ctx, config, { service: database.service, seconds: DB_WAIT_SECONDS });
+    if (!container)
+        return { ok: false, lines: [`FAIL  seed  no running container of ${config.stack}_${database.service} within ${DB_WAIT_SECONDS}s`] };
+    const command = (argv, input) => {
+        const service = config.jobs?.service;
+        if (service === undefined)
+            throw refusal('STACK_SEED_NO_SERVICE', 'a data entry runs its app command in the jobs service; declare deploy.jobs of the environment');
+        const task = serviceContainer(ctx, config, service);
+        if (!task)
+            return { status: null, stdout: '', stderr: '', error: new Error(`no running container of ${config.stack}_${service}`) };
+        return tool(ctx, 'docker', ['exec', '-i', task, ...argv], { input });
+    };
+    return seedStep({ ctx, repoRoot: config.repoRoot, env: config.env, target: f.containerTarget(ctx, container), execute: true, command });
+}

package/sync/canon-layout.d.mts

@@ -0,0 +1,38 @@
+/** The print width of the canon config. */
+export declare const CANON_PRINT_WIDTH = 120;
+/** One indent level of code (`tabWidth` of the canon config). */
+export declare const CANON_INDENT = "    ";
+/** One indent level of JSON (the canon config's override for `*.json`). */
+export declare const CANON_JSON_INDENT = "  ";
+/**
+ * `head` + an array literal of the items + `tail`, the way Prettier prints it: `head[a, b]tail` on one line while it fits the print width,
+ * else every item on its own line with a trailing comma.
+ *
+ * @param {object} list - The text before the array, its items and the text after it.
+ * @returns {string} The lines, without a final newline.
+ */
+export declare const canonList: ({ head, items, tail }: {
+    head: string;
+    items: readonly string[];
+    tail?: string;
+}) => string;
+/**
+ * A named import, the way Prettier prints it: `import { a, b } from "x"` on one line while it fits, else one name a line; an import of one
+ * name is never broken.
+ *
+ * @param {object} declaration - The imported names, the module and whether it imports types only.
+ * @returns {string} The lines, without a final newline.
+ */
+export declare const canonImport: ({ names, from, type }: {
+    names: readonly string[];
+    from: string;
+    type?: boolean;
+}) => string;
+/**
+ * A JSON document as the canon prints a `.json` file (not a `package.json`, which Prettier prints the way `JSON.stringify` does): every
+ * object open one key a line, an array of scalars on one line while it fits, and a final newline.
+ *
+ * @param {unknown} value - The document.
+ * @returns {string} Its text.
+ */
+export declare const canonJson: (value: unknown) => string;

package/sync/canon-layout.mjs

@@ -0,0 +1,62 @@
+// canon-layout.mts - the layout of the canon Prettier config (@starci/prettier-config) that the code and JSON `starci app sync` renders by
+// itself are written in, so a managed file passes the app's `prettier --check` (HFS_FORMAT, the pre-commit hook) as rendered and formatting it
+// never makes HFS_SYNC_DRIFT. A rendered file is laid out the way Prettier lays it out: a list on one line while the line fits the print width,
+// else one item a line with a trailing comma. src/sync-prettier.spec.mts holds these numbers to the canon config and every managed file to
+// `prettier --check`.
+/** The print width of the canon config. */
+export const CANON_PRINT_WIDTH = 120;
+/** One indent level of code (`tabWidth` of the canon config). */
+export const CANON_INDENT = '    ';
+/** One indent level of JSON (the canon config's override for `*.json`). */
+export const CANON_JSON_INDENT = '  ';
+/** `open` + the items + `close` on one line when it fits or `breaks` is false, else one item a line, one level deeper, with a trailing comma. */
+function fitted(open, items, close, flat, breaks) {
+    if (!breaks || flat.length <= CANON_PRINT_WIDTH)
+        return flat;
+    return [open, ...items.map((item) => `${CANON_INDENT}${item},`), close].join('\n');
+}
+/**
+ * `head` + an array literal of the items + `tail`, the way Prettier prints it: `head[a, b]tail` on one line while it fits the print width,
+ * else every item on its own line with a trailing comma.
+ *
+ * @param {object} list - The text before the array, its items and the text after it.
+ * @returns {string} The lines, without a final newline.
+ */
+export const canonList = ({ head, items, tail = '' }) => fitted(`${head}[`, items, `]${tail}`, `${head}[${items.join(', ')}]${tail}`, items.length > 0);
+/**
+ * A named import, the way Prettier prints it: `import { a, b } from "x"` on one line while it fits, else one name a line; an import of one
+ * name is never broken.
+ *
+ * @param {object} declaration - The imported names, the module and whether it imports types only.
+ * @returns {string} The lines, without a final newline.
+ */
+export const canonImport = ({ names, from, type = false }) => {
+    const head = `import ${type ? 'type ' : ''}{`;
+    const tail = `} from ${JSON.stringify(from)}`;
+    return fitted(head, names, tail, `${head} ${names.join(', ')} ${tail}`, names.length > 1);
+};
+const isContainer = (value) => typeof value === 'object' && value !== null;
+const isEmpty = (value) => (Array.isArray(value) ? value.length === 0 : Object.keys(value).length === 0);
+/** One JSON value at `indent`, after `prefix` (`"key": `) and before `suffix` (`,` or nothing), as the canon prints a `.json` file. */
+function jsonValue(value, indent, prefix, suffix) {
+    if (!isContainer(value) || isEmpty(value))
+        return `${indent}${prefix}${JSON.stringify(value)}${suffix}`;
+    const inner = `${indent}${CANON_JSON_INDENT}`;
+    if (Array.isArray(value)) {
+        // An array of scalars stays on one line while it fits; an array holding an object or a list breaks, since the object is kept open.
+        const flat = `${indent}${prefix}[${value.map((item) => JSON.stringify(item)).join(', ')}]${suffix}`;
+        if (value.every((item) => !isContainer(item) || isEmpty(item)) && flat.length <= CANON_PRINT_WIDTH)
+            return flat;
+        return [`${indent}${prefix}[`, ...value.map((item, index) => jsonValue(item, inner, '', index < value.length - 1 ? ',' : '')), `${indent}]${suffix}`].join('\n');
+    }
+    const entries = Object.entries(value);
+    return [`${indent}${prefix}{`, ...entries.map(([key, item], index) => jsonValue(item, inner, `${JSON.stringify(key)}: `, index < entries.length - 1 ? ',' : '')), `${indent}}${suffix}`].join('\n');
+}
+/**
+ * A JSON document as the canon prints a `.json` file (not a `package.json`, which Prettier prints the way `JSON.stringify` does): every
+ * object open one key a line, an array of scalars on one line while it fits, and a final newline.
+ *
+ * @param {unknown} value - The document.
+ * @returns {string} Its text.
+ */
+export const canonJson = (value) => `${jsonValue(value, '', '', '')}\n`;

package/sync/ci-commands.d.mts

@@ -11,9 +11,10 @@ interface CiSource {
 /** jest --shard=i/N gives each shard ceil(specs / N) spec files in order, so shard N is empty unless (N - 1) * ceil(specs / N) < specs. */
 export declare function filledShards(specs: number, wanted: number): number;
 /** An omitted quality declaration preserves hosted Sonar, required OIDC Codecov, and the high production dependency audit. */
-export declare function ciWorkflowCommands(source: CiSource | undefined, lcovReport?: string, quality?: Declaration, { nodeMajor, app, packages }?: {
+export declare function ciWorkflowCommands(source: CiSource | undefined, lcovReport?: string, quality?: Declaration, { nodeMajor, app, packages, rootPackages }?: {
     nodeMajor?: string;
     packages?: boolean;
+    rootPackages?: boolean;
     app?: {
         sides: {
             fe: {

package/sync/ci-commands.mjs

@@ -31,7 +31,7 @@ function codecovSteps(lcovReport, codecov) {
     ].join('\n');
 }
 /** Sonar is required: on every full run it consumes the test coverage and lint artifacts, and a missing token fails the job with a clear refusal. */
-function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, timeout) {
+function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, timeout, scopes) {
     if (!sonar)
         return '';
     const condition = SONAR_CONDITION;
@@ -64,7 +64,7 @@ function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, timeout) {
         '          pattern: sonar-lint-*',
         '          path: reports',
         '          merge-multiple: true',
-        ...sonarMergeSteps(condition),
+        ...sonarMergeSteps(condition, scopes),
         '      - uses: SonarSource/sonarqube-scan-action@c7ee0f9df90b7aa20e8dcf9695dcfe2e7da5b4f2 # v7.2.1',
         `        if: ${condition}`,
         '      - uses: SonarSource/sonarqube-quality-gate-action@7a5fffe8e523c40e0c740b6bc2712ab503e52efa # v1.2.1',
@@ -137,15 +137,15 @@ function frontendBuild(source, app) {
     ].filter(Boolean).join('\n')).join('\n');
     return { env: singleEnv, steps };
 }
-/** The per-side lint reports (one artifact per lint matrix side) join into the one reports/lint.sonar.json the Sonar import reads, even when one side wrote none. The local release gate writes the same file with mergeSonarReports (release/lint-report.mjs): keep both identical. */
-function sonarMergeSteps(condition) {
+/** The per-scope lint reports (one artifact per lint matrix scope) join into the one reports/lint.sonar.json the Sonar import reads, even when one scope wrote none. The local release gate writes the same file with mergeSonarReports (release/lint-report.mjs): keep both identical. */
+function sonarMergeSteps(condition, scopes) {
     return [
         '      - name: merge Sonar lint reports',
         `        if: ${condition}`,
         '        run: |',
         "          node --input-type=module <<'NODE'",
         "          import fs from 'node:fs';",
-        "          const files = ['reports/lint.be.sonar.json', 'reports/lint.fe.sonar.json'];",
+        `          const files = [${scopes.map((scope) => `'reports/lint.${scope}.sonar.json'`).join(', ')}];`,
         "          const reports = files.filter(file => fs.existsSync(file)).map(file => JSON.parse(fs.readFileSync(file, 'utf8')));",
         '          const rules = [...new Map(reports.flatMap(report => report.rules).map(rule => [rule.id, rule])).values()];',
         '          const issues = reports.flatMap(report => report.issues);',
@@ -179,7 +179,7 @@ function ciJobSettings(declaration, source) {
     };
 }
 /** An omitted quality declaration preserves hosted Sonar, required OIDC Codecov, and the high production dependency audit. */
-export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info', quality = undefined, { nodeMajor = '22', app, packages = false } = {}) {
+export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info', quality = undefined, { nodeMajor = '22', app, packages = false, rootPackages = false } = {}) {
     const configuredSonar = quality === undefined ? { token: 'SONAR_TOKEN', hostVar: 'SONAR_HOST_URL' } : quality.sonar;
     const sonar = configuredSonar?.wiring === 'not-used' || configuredSonar?.mode === 'disabled' ? null : configuredSonar;
     const codecov = quality?.codecov ?? { enabled: true, auth: 'oidc' };
@@ -188,8 +188,11 @@ export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info',
     const build = frontendBuild(source, app);
     const settings = ciJobSettings(buildDeclaration(source), source);
     const side = '${{ matrix.side }}';
+    // The lint matrix: one job per side, and one for the root packages of an app that has them (their scope runs whatever became of the sides').
+    const scopes = ['be', 'fe', ...(rootPackages ? ['packages'] : [])];
     return {
         ...settings,
+        lintSides: `[${scopes.join(', ')}]`,
         lcovShardsDir: lcovReport.split('/').slice(0, -1).concat('shards').join('/'),
         // The istanbul JSON a shard writes beside the lcov (STARCI_COVERAGE_SHARD=1): what the coverage job merges.
         shardCoverageReport: lcovReport.split('/').slice(0, -1).concat('coverage-final.json').join('/'),
@@ -224,7 +227,7 @@ export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info',
         codecovSteps: codecovSteps(lcovReport, codecov),
         verdictSonarNeed: sonar ? ', sonar' : '',
         verdictSonarCheck: sonar ? `\n          if [[ "$FULL" == true && "$CHECKS" == true ]]; then expect sonar success; else expect sonar idle; fi` : '',
-        sonarJob: sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, settings.timeoutSonar),
+        sonarJob: sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, settings.timeoutSonar, scopes),
         lcovArtifact,
     };
 }

package/sync/index.d.mts

@@ -1,3 +1,4 @@
+import { type PackagesCoverage } from '../runtime/scripts/hfs/coverage-scope.mjs';
 import { type RepoView } from '../runtime/scripts/hfs/slots.mjs';
 import type { AppRepo } from '../runtime/scripts/hfs/slot-app-view.mjs';
 import type { Slot, SlotManifest } from '../runtime/scripts/hfs/manifest-shape.mjs';
@@ -68,6 +69,7 @@ export interface AppSourceFacts {
     read: (file: string) => string;
     workPresent: boolean;
     hasImage: (file: string) => boolean;
+    hasContracts: boolean;
     modules?: readonly string[];
     otherPackages?: readonly string[];
     stack: any;
@@ -146,6 +148,8 @@ export declare function sonarScope(presets: Presets | null | undefined): {
 };
 /** The managed ESLint config at the app root that lints the root workspace packages. */
 export declare const PACKAGES_LINT_FILE = "eslint.config.mjs";
+/** The app-relative folders of the root packages whose logic the back end's unit run measures: every module package and every other package, never the registry. */
+export declare const rootPackageFolders: (source: Partial<Pick<AppSourceFacts, "modules" | "otherPackages">> | undefined) => string[];
 export declare function appSource(root: string, { parseYaml, notices }?: {
     parseYaml?: ParseYaml | undefined;
     notices?: string[] | undefined;
@@ -188,12 +192,19 @@ export declare function imageApps(app: ResolvedApp, source: Partial<Pick<AppSour
 /**
  * The Dockerfile of every declared app, [{ path, content }] (app-relative): written once by starci app scaffold from templates/<side>/image/<kind>
  * and then the app's own, judged by the docker rules (R187-R191). A Next image copies the fe packages only when the fe side opts into
- * them and the be contracts only when the fe side reads them, so each COPY names a folder the app has.
+ * them and the be contracts only when the fe side reads them and the back end holds them (`source.hasContracts`: a back end that emits no
+ * contract has no be/contracts/, and a COPY of a missing folder fails the image build), so each COPY names a folder the app has.
  */
-export declare function imageFiles(app: ResolvedApp, source?: Partial<Pick<AppSourceFacts, 'hasImage'>>): {
+export declare function imageFiles(app: ResolvedApp, source?: Partial<Pick<AppSourceFacts, 'hasImage' | 'hasContracts'>>): {
     path: string;
     content: string;
 }[];
+/** Every value a template of `scope` can name, derived from hfs.json and the presets. */
+/**
+ * The `packages` option of the managed be/jest.config.js (`starciJestConfig`), laid out as prettier lays it out (width 120, indent 4): the root packages whose
+ * specs the unit run holds, with the files measured in them; an app without one has no such option.
+ */
+export declare function jestPackagesSource(packages: PackagesCoverage): string;
 export declare function variables(app: ResolvedApp, scope: string, presets: Presets | null | undefined, sonarKey: string | null | undefined, manifest?: SlotManifest, source?: Pick<AppSourceFacts, 'files' | 'read'> & Partial<AppSourceFacts>): Record<string, string>;
 /**
  * The rendered targets of an app declaration. Without source facts the app counts the back-end source files its own targets