@starci/hfs 5.1.0 → 5.3.0

package/stack/local-state.d.mts

@@ -0,0 +1,35 @@
+/** What the environment recorded about itself. */
+export interface LocalRecord {
+    processes: Record<string, {
+        pid: number;
+        startedAt: string;
+        port: number | null;
+    }>;
+    ports: Record<string, number>;
+    receipts: {
+        migrate?: {
+            at: string;
+            digest: string;
+        };
+        seed: Record<string, {
+            at: string;
+            digest: string;
+        }>;
+        setup: Record<string, {
+            at: string;
+            digest: string;
+        }>;
+        database?: {
+            at: string;
+            role: string;
+        };
+    };
+}
+/** The directory of one environment's state: `<state base>/stack/<project>/<env>`. */
+export declare const stateDirectory: (env: NodeJS.ProcessEnv, project: string, environment: string) => string;
+/** The log file of one process or service. */
+export declare const logFile: (dir: string, name: string) => string;
+/** Reads the record; an absent or damaged file is an empty record (the environment then reads as not started). */
+export declare function readRecord(dir: string): LocalRecord;
+/** Writes the record atomically; it holds ids, ports and digests, never a value. */
+export declare function writeRecord(dir: string, record: LocalRecord): void;

package/stack/local-state.mjs

@@ -0,0 +1,29 @@
+// local-state.mjs - where a dev environment keeps what it started: process ids, logs and receipts, under the per-host state base
+// (STARCI_LOCAL_ROOT, else the runtime's .runtime), never in the app's checkout (README "Harness state lives in the runtime").
+import fs from 'node:fs';
+import path from 'node:path';
+import { starciLocalRoot } from '../runtime/engine/runtime-root.mjs';
+const empty = () => ({ processes: {}, ports: {}, receipts: { seed: {}, setup: {} } });
+/** The directory of one environment's state: `<state base>/stack/<project>/<env>`. */
+export const stateDirectory = (env, project, environment) => path.join(starciLocalRoot(env), 'stack', project, environment);
+/** The log file of one process or service. */
+export const logFile = (dir, name) => path.join(dir, 'logs', `${name}.log`);
+/** Reads the record; an absent or damaged file is an empty record (the environment then reads as not started). */
+export function readRecord(dir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(dir, 'state.json'), 'utf8'));
+        const base = empty();
+        return { processes: parsed.processes ?? base.processes, ports: parsed.ports ?? base.ports, receipts: { ...base.receipts, ...parsed.receipts } };
+    }
+    catch {
+        return empty();
+    }
+}
+/** Writes the record atomically; it holds ids, ports and digests, never a value. */
+export function writeRecord(dir, record) {
+    fs.mkdirSync(path.join(dir, 'logs'), { recursive: true });
+    const target = path.join(dir, 'state.json');
+    const temporary = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(record, null, 2)}\n`);
+    fs.renameSync(temporary, target);
+}

package/stack/local-status.d.mts

@@ -0,0 +1,6 @@
+import type { StackContext } from './context.mjs';
+import type { ActionResult } from './remote.mjs';
+import type { LocalConfig } from './local-config.mjs';
+import type { LocalDeps } from './local-run.mjs';
+/** `status` for a dev environment. */
+export declare function statusLocal(ctx: StackContext, local: LocalConfig, _options?: Record<string, unknown>, deps?: LocalDeps): Promise<ActionResult>;

package/stack/local-status.mjs

@@ -0,0 +1,36 @@
+import { firstLine } from './context.mjs';
+import { migrationsDigest } from './local-up.mjs';
+import { compose, isAlive, probe, stateOf } from './local-run.mjs';
+import { readRecord } from './local-state.mjs';
+/** `status` for a dev environment. */
+export async function statusLocal(ctx, local, _options = {}, deps = {}) {
+    const record = readRecord(stateOf(ctx, local));
+    const lines = [];
+    let ok = true;
+    const mark = (good, text) => { ok &&= good; lines.push(`${good ? 'ok    ' : 'FAIL  '}${text}`); };
+    for (const service of local.services) {
+        const id = firstLine((await compose(ctx, local, ['ps', '-q', service.name])).stdout);
+        if (!id) {
+            mark(false, `service ${service.name}: not created`);
+            continue;
+        }
+        const inspected = ctx.spawn('docker', ['inspect', '-f', '{{.State.Status}} {{if .State.Health}}{{.State.Health.Status}}{{else}}nohealth{{end}}', id]);
+        const [state, health] = firstLine(inspected.stdout).split(' ');
+        mark(state === 'running' && (service.wait !== 'healthy' || health === 'healthy'), `service ${service.name}: ${state}${health === 'nohealth' ? '' : `, ${health}`}`);
+    }
+    const alive = deps.alive ?? isAlive;
+    for (const run of local.processes) {
+        const entry = record.processes[run.name];
+        mark(entry !== undefined && alive(entry.pid), entry ? `process ${run.name}: pid ${entry.pid} ${alive(entry.pid) ? 'alive' : 'gone'}` : `process ${run.name}: not started`);
+    }
+    if (local.database) {
+        const receipt = record.receipts.migrate;
+        const current = migrationsDigest(local.repoRoot);
+        mark(receipt?.digest === current, receipt ? `migrations: receipt ${receipt.digest} ${receipt.digest === current ? 'is current' : `is stale, the folder is ${current}`}` : 'migrations: no receipt');
+    }
+    for (const row of local.ready) {
+        const result = await probe(ctx, local, row);
+        mark(result.ok, `ready ${result.detail}`);
+    }
+    return { ok, lines, data: { processes: record.processes } };
+}

package/stack/local-up.d.mts

@@ -0,0 +1,11 @@
+import type { StackContext } from './context.mjs';
+import type { ActionResult } from './remote.mjs';
+import type { LocalConfig } from './local-config.mjs';
+import type { LocalDeps } from './local-run.mjs';
+/** The digest of the migration folder (names and contents): what a migrate receipt records. */
+export declare function migrationsDigest(repoRoot: string): string;
+/** `up` for a dev environment. */
+export declare function upLocal(ctx: StackContext, local: LocalConfig, { execute, timeoutSeconds }?: {
+    execute?: boolean;
+    timeoutSeconds?: number;
+}, deps?: LocalDeps): Promise<ActionResult>;

package/stack/local-up.mjs

@@ -0,0 +1,169 @@
+// 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.
+// 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 { 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 { readRecord, writeRecord } from './local-state.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. */
+export function migrationsDigest(repoRoot) {
+    const directory = path.join(repoRoot, 'db', 'migrations');
+    const hash = crypto.createHash('sha256');
+    let names = [];
+    try {
+        names = fs.readdirSync(directory).filter((name) => name.endsWith('.sql')).sort();
+    }
+    catch {
+        return 'none';
+    }
+    for (const name of names)
+        hash.update(name).update(fs.readFileSync(path.join(directory, name)));
+    return hash.digest('hex').slice(0, 16);
+}
+/** Creates the environment's own login role and database if absent and sets its password (psql in the db container, SQL on stdin, never argv). */
+async function provisionDatabase(ctx, local, custody) {
+    const database = local.database;
+    if (!database)
+        return 'database: none declared';
+    const password = custody.values.get(database.password.key) ?? '';
+    if (!SAFE_PASSWORD.test(password))
+        throw refusal('STACK_LOCAL_DB_PASSWORD', `${database.password.key} must be at least 8 characters of letters, digits, dash and underscore (the generated password kind is); the owner replaces it with secret unset and secret init`);
+    const sql = [
+        `DO $do$ BEGIN IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = '${database.role}') THEN CREATE ROLE "${database.role}" LOGIN SUPERUSER PASSWORD '${password}'; ELSE ALTER ROLE "${database.role}" LOGIN SUPERUSER PASSWORD '${password}'; END IF; END $do$;`,
+        `SELECT 'CREATE DATABASE "${database.name}" OWNER "${database.role}"' WHERE NOT EXISTS (SELECT FROM pg_database WHERE datname = '${database.name}')\\gexec`,
+        '',
+    ].join('\n');
+    const result = await compose(ctx, local, ['exec', '-T', database.service, 'psql', '-v', 'ON_ERROR_STOP=1', '-U', database.adminUser, '-d', 'postgres'], { values: composeValues(local, custody), input: sql });
+    if (result.status !== 0)
+        throw failure('STACK_LOCAL_DB_ROLE', `could not provision the role ${database.role}: ${(result.stderr.trim().split(/\r?\n/u)[0] ?? '').replaceAll(password, '[redacted]')}`);
+    return `database: role ${database.role} and database ${database.name} ready on port ${local.ports[database.port]}`;
+}
+/** Gives the app role the migrations created its own password for this environment (cluster roles are never shared: the db container is this environment's alone). */
+async function appRolePassword(ctx, local, custody) {
+    const database = local.database;
+    if (!database?.appRole || !database.appPassword)
+        return '';
+    const password = custody.values.get(database.appPassword.key) ?? '';
+    if (!SAFE_PASSWORD.test(password))
+        throw refusal('STACK_LOCAL_DB_PASSWORD', `${database.appPassword.key} must be at least 8 characters of letters, digits, dash and underscore`);
+    const sql = `DO $do$ BEGIN IF EXISTS (SELECT FROM pg_roles WHERE rolname = '${database.appRole}') THEN ALTER ROLE "${database.appRole}" LOGIN PASSWORD '${password}'; ELSE RAISE EXCEPTION 'role ${database.appRole} does not exist: the migrations create it'; END IF; END $do$;\n`;
+    const result = await compose(ctx, local, ['exec', '-T', database.service, 'psql', '-v', 'ON_ERROR_STOP=1', '-U', database.adminUser, '-d', database.name], { values: composeValues(local, custody), input: sql });
+    if (result.status !== 0)
+        throw failure('STACK_LOCAL_DB_ROLE', `could not set the password of ${database.appRole}: ${(result.stderr.trim().split(/\r?\n/u)[0] ?? '').replaceAll(password, '[redacted]')}`);
+    return `, ${database.appRole} password set`;
+}
+/** Migrates through `starci app db migrate` in this process; the URL stays in the environment of that call. */
+async function migrate(ctx, local, custody, deps) {
+    const database = local.database;
+    const url = databaseUrl(local, custody);
+    if (!database || url === null)
+        return 'migrate: no database declared';
+    const container = firstLine((await compose(ctx, local, ['ps', '-q', database.service])).stdout);
+    const env = { ...ctx.env, DATABASE_URL: url, STARCI_DB_CONTAINER: container };
+    const run = deps.migrate ?? (async (urlEnv, environment, cwd) => {
+        const { main } = await import('../src/main.mjs');
+        return main(['db', 'migrate', '--db-url-env', urlEnv, '--execute'], { cwd, env: environment, stdout: () => { }, stderr: () => { } });
+    });
+    const code = await run('DATABASE_URL', env, local.repoRoot);
+    if (code !== 0)
+        throw failure('STACK_LOCAL_MIGRATE', `starci app db migrate exited ${code}; run it with --db-url-env DATABASE_URL to read its report`);
+    const dir = stateOf(ctx, local);
+    const record = readRecord(dir);
+    record.receipts.migrate = { at: new Date(ctx.now()).toISOString(), digest: migrationsDigest(local.repoRoot) };
+    writeRecord(dir, record);
+    return `migrate: applied, receipt ${record.receipts.migrate.digest}${await appRolePassword(ctx, local, custody)}`;
+}
+/** 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);
+    const record = readRecord(dir);
+    const out = [];
+    for (const run of local.seed.filter((item) => item.after === after)) {
+        if (record.receipts.seed[run.name]?.digest === commandDigest(run)) {
+            out.push(`seed ${run.name}: already done`);
+            continue;
+        }
+        await runCommand(ctx, local, run, runEnvironment(ctx, local, run, custody, 'owner'));
+        record.receipts.seed[run.name] = { at: new Date(ctx.now()).toISOString(), digest: commandDigest(run) };
+        writeRecord(dir, record);
+        out.push(`seed ${run.name}: done`);
+    }
+    return out;
+}
+/** Starts each native process that is not already running. */
+function startProcesses(ctx, local, custody, deps) {
+    const dir = stateOf(ctx, local);
+    const record = readRecord(dir);
+    const out = [];
+    const alive = deps.alive ?? isAlive;
+    for (const run of local.processes) {
+        const known = record.processes[run.name];
+        if (known && alive(known.pid)) {
+            out.push(`process ${run.name}: running (pid ${known.pid})`);
+            continue;
+        }
+        const pid = startProcess(ctx, local, run, runEnvironment(ctx, local, run, custody, 'app'));
+        record.processes[run.name] = { pid, startedAt: new Date(ctx.now()).toISOString(), port: run.port === null ? null : (local.ports[run.port] ?? null) };
+        out.push(`process ${run.name}: started (pid ${pid})`);
+    }
+    record.ports = { ...local.ports };
+    writeRecord(dir, record);
+    return out;
+}
+/** The plan a dry run prints. */
+function plan(local, missing) {
+    return [
+        `plan custody: ${missing.length ? `missing ${missing.join(', ')}: ${missingStep(local, missing)}` : 'open the sealed dev values into host-local files'}`,
+        ...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.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}`),
+    ];
+}
+/** `up` for a dev environment. */
+export async function upLocal(ctx, local, { execute = false, timeoutSeconds = DEFAULT_TIMEOUT_SECONDS } = {}, deps = {}) {
+    const host = await preflight(ctx, local, deps);
+    if (!host.ok)
+        return hostRefusal(host.lines);
+    const missing = missingKeys(local);
+    if (!execute)
+        return { ok: missing.length === 0, lines: [...host.lines, ...plan(local, missing), 'dry run: nothing was started; arm it with --execute'], data: { rows: host.rows } };
+    const lines = [...host.lines];
+    const custody = openCustody(ctx, local);
+    lines.push(`custody: ${custody.values.size} key file(s) in the host-local directory`);
+    lines.push(...await runSetup(ctx, local, custody));
+    makeDataDirectories(ctx, local);
+    lines.push(...await ensureRuntimeLayers(ctx, local));
+    const values = composeValues(local, custody);
+    const started = await compose(ctx, local, ['up', '-d', ...local.services.map((service) => service.name)], { values, heavy: true, label: 'compose up' });
+    if (started.status !== 0)
+        throw failure('STACK_LOCAL_COMPOSE', `docker compose up failed: ${(started.stderr.trim().split(/\r?\n/u)[0] ?? '').slice(0, 200)}`);
+    const deadline = ctx.now() + timeoutSeconds * 1000;
+    for (const service of local.services) {
+        const ready = await serviceReady(ctx, local, service.name, deadline, deps);
+        lines.push(`service ${ready.detail}`);
+        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));
+    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}`);
+        if (!result.ok)
+            throw failure('STACK_LOCAL_READY', `${row.name} is not ready: ${result.detail}; read a process log with: starci app stack logs --env ${local.env} --service ${local.processes.map((run) => run.name).join('|')}`);
+    }
+    lines.push(...await seed(ctx, local, custody, 'ready'));
+    lines.push(...local.origins.map((origin) => `origin ${origin.name}: ${origin.url.replaceAll(/\$\{port\.([a-z][a-z0-9-]*)\}/gu, (_whole, name) => String(local.ports[name]))}`));
+    return { ok: true, lines, data: { origins: local.origins } };
+}

package/stack/local-verify.d.mts

@@ -0,0 +1,6 @@
+import type { StackContext } from './context.mjs';
+import type { ActionResult } from './remote.mjs';
+import type { LocalConfig } from './local-config.mjs';
+import type { LocalDeps } from './local-run.mjs';
+/** `verify` for a dev environment. */
+export declare function verifyLocal(ctx: StackContext, local: LocalConfig, _options?: Record<string, unknown>, deps?: LocalDeps): Promise<ActionResult>;

package/stack/local-verify.mjs

@@ -0,0 +1,21 @@
+import { refusal } from './errors.mjs';
+import { isAlive, probe, stateOf } from './local-run.mjs';
+import { readRecord } from './local-state.mjs';
+/** `verify` for a dev environment. */
+export async function verifyLocal(ctx, local, _options = {}, deps = {}) {
+    if (local.verify.length === 0)
+        throw refusal('STACK_LOCAL_VERIFY_UNDECLARED', `environment ${local.env} declares no local.verify journey: a liveness probe alone is not verification`);
+    const record = readRecord(stateOf(ctx, local));
+    const alive = deps.alive ?? isAlive;
+    const down = local.processes.filter((run) => !(record.processes[run.name] && alive(record.processes[run.name].pid)));
+    if (down.length)
+        return { ok: false, lines: [`FAIL  ${down.map((run) => run.name).join(', ')} not running: start the environment with starci app stack up --env ${local.env} --execute`] };
+    const lines = [];
+    let ok = true;
+    for (const row of local.verify) {
+        const result = await probe(ctx, local, row);
+        ok &&= result.ok;
+        lines.push(`${result.ok ? 'ok    ' : 'FAIL  '}${result.detail}`);
+    }
+    return { ok, lines, data: { checked: local.verify.length } };
+}

package/stack/runtime-layers.d.mts

@@ -0,0 +1,21 @@
+import type { StackContext } from './context.mjs';
+import type { LocalConfig } from './local-config.mjs';
+/** The registry path of the harness-owned layers: `<prefix><layer>`. */
+export declare const LAYER_PREFIX = "ghcr.io/starci183/";
+/** The layers whose recipe this package ships. */
+export declare const SHIPPED_LAYERS: readonly string[];
+/** The folder holding the recipe of a layer in this package. */
+export declare const recipeDirectory: (layer: string) => string;
+/** One layer an app image builds on: the layer, the reference as the Dockerfile writes it and the tag a local build gives it. */
+export interface LayerUse {
+    layer: string;
+    reference: string;
+    tag: string;
+    dockerfile: string;
+}
+/** The layers `.starcistacks/images/*` of the app builds on (each distinct reference once), from the `FROM` lines of its Dockerfiles. */
+export declare function layersUsed(repoRoot: string): LayerUse[];
+/** The lines of the plan a dry run prints for the layers the app builds on. */
+export declare const layerPlan: (local: LocalConfig) => string[];
+/** Builds every layer the app names that the host neither holds nor can pull; returns one line per layer. */
+export declare function ensureRuntimeLayers(ctx: StackContext, local: LocalConfig): Promise<string[]>;

package/stack/runtime-layers.mjs

@@ -0,0 +1,67 @@
+// runtime-layers.mjs - the harness runtime layers a dev stack builds on (images/README.md "The OpenClaw runtime layer"; R374 STACKS_IMAGE_BASE_NOT_FORK).
+// An app image folder `.starcistacks/images/<name>/Dockerfile` is `FROM ghcr.io/starci183/<layer>:<tag>[@sha256:<digest>]`. While the harness has not
+// published that layer (or the host cannot pull it), `starci app stack up` builds it from the recipe this package ships (stack/images/<layer>/,
+// byte-equal to the harness repository's images/<layer>/, which `npm run bundles` copies and a spec compares) and tags it with the reference the
+// app names minus its digest, so the compose build of the app image finds it in the local store. The build is a governed heavy command
+// (hard rule 8): an agent never runs docker by hand. A reference whose image the host already holds, or can pull, is left alone.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { failure } from './errors.mjs';
+/** The registry path of the harness-owned layers: `<prefix><layer>`. */
+export const LAYER_PREFIX = 'ghcr.io/starci183/';
+/** The layers whose recipe this package ships. */
+export const SHIPPED_LAYERS = Object.freeze(['openclaw-runtime']);
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+/** The folder holding the recipe of a layer in this package. */
+export const recipeDirectory = (layer) => path.join(HERE, 'images', layer);
+/** The layers `.starcistacks/images/*` of the app builds on (each distinct reference once), from the `FROM` lines of its Dockerfiles. */
+export function layersUsed(repoRoot) {
+    const folder = path.join(repoRoot, '.starcistacks', 'images');
+    if (!fs.existsSync(folder))
+        return [];
+    const found = new Map();
+    for (const entry of fs.readdirSync(folder, { withFileTypes: true }).filter((item) => item.isDirectory()).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+        const dockerfile = path.join(folder, entry.name, 'Dockerfile');
+        if (!fs.existsSync(dockerfile))
+            continue;
+        for (const line of fs.readFileSync(dockerfile, 'utf8').split(/\r?\n/u)) {
+            const from = /^\s*FROM\s+(?:--\S+\s+)*(\S+)/iu.exec(line)?.[1];
+            if (from?.startsWith(LAYER_PREFIX) !== true)
+                continue;
+            const reference = from;
+            const tag = reference.replace(/@sha256:[0-9a-f]+$/u, '');
+            const layer = tag.slice(LAYER_PREFIX.length).replace(/:.*$/u, '');
+            if (SHIPPED_LAYERS.includes(layer) && !found.has(reference))
+                found.set(reference, { layer, reference, tag: tag.includes(':') ? tag : `${tag}:latest`, dockerfile: path.relative(repoRoot, dockerfile).split(path.sep).join('/') });
+        }
+    }
+    return [...found.values()];
+}
+/** Whether the host holds `reference` or can pull it: the local store first, then the registry's manifest. */
+async function available(ctx, use) {
+    if ((await ctx.spawn('docker', ['image', 'inspect', use.tag])).status === 0)
+        return true;
+    return (await ctx.spawn('docker', ['manifest', 'inspect', use.reference])).status === 0;
+}
+/** The lines of the plan a dry run prints for the layers the app builds on. */
+export const layerPlan = (local) => layersUsed(local.repoRoot).map((use) => `plan runtime layer ${use.layer}: ${use.tag} is built from the shipped recipe when the host holds none and the registry has none`);
+/** Builds every layer the app names that the host neither holds nor can pull; returns one line per layer. */
+export async function ensureRuntimeLayers(ctx, local) {
+    const lines = [];
+    for (const use of layersUsed(local.repoRoot)) {
+        if (await available(ctx, use)) {
+            lines.push(`runtime layer ${use.layer}: ${use.tag} is available`);
+            continue;
+        }
+        const recipe = recipeDirectory(use.layer);
+        if (!fs.existsSync(path.join(recipe, 'Dockerfile')))
+            throw failure('STACK_LOCAL_RUNTIME_LAYER', `${use.dockerfile} builds on ${use.reference}, which is not published, and this package ships no recipe for ${use.layer}`);
+        const argv = ['docker', 'build', '-t', use.tag, recipe];
+        const built = ctx.heavy ? await ctx.heavy({ kind: 'build', label: `${local.project} runtime layer ${use.layer}`, cwd: local.repoRoot, argv, env: ctx.env }) : await ctx.spawn('docker', argv.slice(1), { cwd: local.repoRoot, env: ctx.env });
+        if (built.status !== 0)
+            throw failure('STACK_LOCAL_RUNTIME_LAYER', `docker build of the runtime layer ${use.layer} failed: ${(built.stderr.trim().split(/\r?\n/u)[0] ?? '').slice(0, 200)}`);
+        lines.push(`runtime layer ${use.layer}: ${use.reference} is not published; built ${use.tag} from the recipe this package ships`);
+    }
+    return lines;
+}

package/sync/hygiene.mjs

@@ -45,6 +45,8 @@ const PLAINTEXT_NAME = /(^|\/)(\.env(\..*)?|[^/]*\.(pem|key|identity|age))$/;
 /** The app root's work tree and stack tree, app-relative (`starci app check --staged` runs at the app root). */
 const WORK = '.starciwork/';
 const STACKS = '.starcistacks/';
+/** The committed check cache: written by the CLI, judged by what its files hold (secret-records.mjs through the secret judgement), never by a `secrets/` folder in its path. */
+const CACHE = '.starcistacks/cache/';
 const GUARDED = (file) => file.startsWith(WORK) || file.startsWith(STACKS);
 /** The subset of `files` git ignores (as if untracked), asked in one call: a Set of paths. */
 function ignoredAmong(cwd, files) {
@@ -67,7 +69,7 @@ export function hygieneFindings(files, ignored) {
         if (file.startsWith(WORK) && ignored.has(file)) {
             findings.push({ file, code: 'HFS_WORK_AGENT_DATA', message: 'is agent output, which .starciwork/.gitignore refuses; keep it in the scratchpad or the blob store' });
         }
-        if (file.startsWith(STACKS) && !/\.enc(?:\.yaml)?$/.test(file) && !file.endsWith('.env.example') && !file.endsWith('/secrets/.gitkeep')) {
+        if (file.startsWith(STACKS) && !file.startsWith(CACHE) && !/\.enc(?:\.yaml)?$/.test(file) && !file.endsWith('.env.example') && !file.endsWith('/secrets/.gitkeep')) {
             if (file.includes('/secrets/'))
                 findings.push({ file, code: 'HFS_PLAINTEXT_SECRET', message: 'sits under secrets/ but is not sealed; only <slug>.enc may be tracked' });
             else if (PLAINTEXT_NAME.test(file))

package/sync/index.d.mts

@@ -64,6 +64,8 @@ export interface AppSourceFacts {
     read: (file: string) => string;
     workPresent: boolean;
     hasImage: (file: string) => boolean;
+    modules?: readonly string[];
+    otherPackages?: readonly string[];
     stack: any;
     quality: any;
     badges: string;
@@ -138,12 +140,8 @@ export declare function sonarScope(presets: Presets | null | undefined): {
     tests: string[];
     exclusions: string[];
 };
-/**
- * The be source of the app at `root` the coverage components read: { files, read }, `files` be-relative posix paths of every `*.ts` file under
- * be/apps and be/src (build output and dependencies skipped) and `read` their text. `workPresent` records whether the optional
- * lite brand tree exists, so sync can preserve its absence. `hasImage` identifies authored optional Dockerfiles without reading
- * their content. An app with no be folder has no source files.
- */
+/** The managed ESLint config at the app root that lints the root workspace packages. */
+export declare const PACKAGES_LINT_FILE = "eslint.config.mjs";
 export declare function appSource(root: string, { parseYaml, notices }?: {
     parseYaml?: ParseYaml | undefined;
     notices?: string[] | undefined;
@@ -178,7 +176,7 @@ export declare function jestCoverageSource(coverage: {
  * `docker:build:<app>` builds the image of one app (the exact command its Dockerfile header states, tag `<project>/<app>:dev`) and
  * `docker:build` builds every image, one after the other, never pushing.
  */
-export declare function appScripts(app: ResolvedApp, source: Partial<Pick<AppSourceFacts, 'hasImage'>> | undefined): string;
+export declare function appScripts(app: ResolvedApp, source: Partial<Pick<AppSourceFacts, 'hasImage' | 'modules'>> | undefined): string;
 /** The stylesheets of the fe side the CSS canon judges, relative to fe/: every app and every workspace package (slot fe.route, fe.package.*). */
 export declare const STYLE_GLOB = "{apps,packages}/*/src/**/*.css";
 /** The apps images.yml builds (one matrix entry per declared app): name and Dockerfile, be then fe, then a lite app's db image. */
@@ -192,14 +190,13 @@ export declare function imageFiles(app: ResolvedApp, source?: Partial<Pick<AppSo
     path: string;
     content: string;
 }[];
-/** Every value a template of `scope` can name, derived from hfs.json and the presets. */
 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 managed content of every target of the app: [{ path, mode, content, hash, scope }], paths app-relative (a side's targets under
- * its folder); a scripts target also carries `scripts`, the parsed block. `sonarKey` is the key the be side's stack declaration
- * names; without one the key is the project.
+ * The rendered targets of an app declaration. Without source facts the app counts the back-end source files its own targets
+ * render (the managed sign-in glue), as a check reading the disk after the targets are written does, so a render of a declaration
+ * alone is already in sync with itself.
  */
-export declare function renderTargets(hfs: unknown, presets: Presets | null | undefined, { sonarKey, readTemplate, manifest, source }?: {
+export declare function renderTargets(hfs: unknown, presets: Presets | null | undefined, options?: {
     sonarKey?: string | null | undefined;
     readTemplate?: (name: string) => string;
     manifest?: SlotManifest;
@@ -212,6 +209,12 @@ export declare function writtenContent(target: RenderedTarget, existing: string
 export declare function writeTargets(root: string, targets: readonly RenderedTarget[]): string[];
 /** The hfs.json object of the app at `root` (validated), or a SyncError. */
 export declare function loadHfs(root: string, manifest?: SlotManifest): Record<string, any>;
+/**
+ * The source facts as they stand once the rendered back-end source files are on disk: a managed `.ts` target of the be side counts as a
+ * file of the app (and reads as its render), so the CI shard count and the coverage scope that count or read the source name the same
+ * files before and after the targets are written, and one sync leaves the app in sync.
+ */
+export declare function settleSource(source: AppSourceFacts, targets: readonly RenderedTarget[]): AppSourceFacts;
 /** The rendered targets of the app at `root`: its hfs.json, the Sonar key the be side's stack declaration names, the presets it installs. */
 export declare function renderRepo(root: string, { presets, parseYaml, notices, manifest }?: {
     presets?: Presets | undefined;