@starci/hfs 5.3.0 → 5.5.0

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) {

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: {