@starci/hfs 5.0.8 → 5.2.0

package/runtime/scripts/hfs/explicit-surface-rule.mjs

@@ -0,0 +1,59 @@
+import { declarationSurface, isEmittableSource } from '../lib/declaration-surface.mjs';
+/** What to write, by what the classifier says to annotate. */
+const HINTS = {
+    'return type': 'Write the return type after the parameter list: `(): Result =>` or `function name(): Result`.',
+    'variable type': 'Give the variable a type: `export const name: Result = ...`.',
+    'parameter type': 'Give the parameter a type: `(value: Input)`.',
+    'property type': 'Give the property a type: `name: Result = ...`.',
+    'accessor type': 'Give the accessor a type: `get name(): Result` (a setter takes it from its parameter).',
+    'destructured export': 'A destructuring pattern cannot carry a type per name: export each name as its own variable with a type, `export const name: Type = source.name`.',
+    'exported value': 'Declare the type (an interface or a type alias) and annotate the export with it: `export const name: Shape = ...`.',
+};
+/** The `--isolatedDeclarations` flag name TypeScript ends its reasons with says nothing to the reader. */
+const plain = (reason) => reason.replace(/ with --isolatedDeclarations\.?/, '').replace(/\.$/, '');
+/**
+ * The rule. `ts` is the canon's own TypeScript (its peer dependency); the side's `module` option comes from the typed program when the file is linted with one.
+ *
+ * @param input - `ts` is the compiler.
+ * @returns An ESLint rule reporting each export of a TypeScript source whose type is inferred.
+ */
+export const explicitSurfaceRule = ({ ts }) => ({
+    meta: {
+        type: 'problem',
+        docs: { description: 'An exported declaration states its type: the return type, variable type or parameter type is written, not inferred from a body or from other files.' },
+        schema: [],
+        messages: {
+            inferred: 'HFS_EXPLICIT_EXPORT_SURFACE: `{{name}}` is exported with an inferred type ({{reason}}), so importers cannot read it from this file and every one of them is linted again whenever the file changes. Annotate the {{annotate}}. {{hint}}',
+        },
+    },
+    create(context) {
+        return {
+            Program() {
+                const file = context.filename;
+                if (!isEmittableSource(file))
+                    return;
+                const { sourceCode } = context;
+                const module = sourceCode.parserServices?.program?.getCompilerOptions().module;
+                const whole = { start: { line: 1, column: 0 }, end: { line: 1, column: 0 } };
+                let surface;
+                try {
+                    surface = declarationSurface(ts, file, sourceCode.text, module);
+                }
+                catch {
+                    surface = null;
+                }
+                if (surface === null) {
+                    context.report({ loc: whole, messageId: 'inferred', data: { name: 'this file', reason: 'the declaration emit could not read it', annotate: 'exported value', hint: HINTS['exported value'] } });
+                    return;
+                }
+                for (const problem of surface.problems) {
+                    context.report({
+                        loc: { start: sourceCode.getLocFromIndex(problem.start), end: sourceCode.getLocFromIndex(problem.start + problem.length) },
+                        messageId: 'inferred',
+                        data: { name: problem.name, reason: plain(problem.reason), annotate: problem.annotate, hint: HINTS[problem.annotate] },
+                    });
+                }
+            },
+        };
+    },
+});

package/runtime/scripts/hfs/manifest-shape.d.mts

@@ -64,6 +64,7 @@ export interface Slot {
     role?: string;
     importedBy?: string[];
     rewrittenBy?: string;
+    managedOnly?: boolean;
     logic?: string[];
     generatedBy?: string;
 }

package/runtime/scripts/hfs/manifest-shape.mjs

@@ -121,7 +121,7 @@ export const MANIFEST_KINDS = [APP_KIND, RUNTIME_KIND];
 /** The kind of a parsed manifest: `kind`, or app when absent (knowledge/hfs/slots.yaml carries none). */
 export const manifestKind = (m) => (isPlainObject(m) && m.kind !== undefined ? m.kind : APP_KIND);
 const strList = (v) => stringList(v);
-const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exemplifiedBy', 'role', 'importedBy', 'rewrittenBy', 'logic'];
+const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exemplifiedBy', 'role', 'importedBy', 'rewrittenBy', 'logic', 'managedOnly'];
 /** The roles a file slot may play that a rule reads (`role`): the entity registry of persistence.md BE-PERSISTENCE-3 (architecture/entity-registry.mjs). */
 const SLOT_ROLES = ['entity-registry'];
 /** The fields a slot's `lite` overlay may hold: the same keys it would carry in the slot body, resolved under edition lite. */
@@ -235,6 +235,8 @@ function slotListProblems(slot, at) {
         bad.push(`${at}: composedBy must be a non-empty list of unique app kinds`);
     if (slot.budget !== undefined && !budgetValid(slot.budget))
         bad.push(`${at}: budget must map names to positive integers`);
+    if (slot.managedOnly !== undefined && (slot.managedOnly !== true || slot.managedBy === undefined))
+        bad.push(`${at}: managedOnly is true and needs managedBy: the slot only lists files sync renders, and the slot owning the path judges them`);
     for (const key of ['managedBy', 'liteManagedBy'])
         if (slot[key] !== undefined && !NAME.test(String(slot[key])))
             bad.push(`${at}: ${key} must be a template id`);

package/runtime/scripts/hfs/rules/a15-findings.mjs

@@ -33,6 +33,8 @@ import { stacksIngressFindings } from './stacks-ingress.mjs';
 import { stacksLiteBackingFindings } from './stacks-lite-backing.mjs';
 import { stackToolingFindings } from './stack-tooling.mjs';
 import { stacksDeployFindings } from './stacks-deploy.mjs';
+import { stacksLocalFindings } from './stacks-local.mjs';
+import { stacksServiceImageFindings } from './stacks-service-images.mjs';
 import { stacksAuthCookieDomainFindings } from './stacks-auth-cookie-domain.mjs';
 import { ciCustodyFindings } from './ci-custody.mjs';
 import { workflowContextsFindings } from './workflow-contexts.mjs';
@@ -49,6 +51,7 @@ export const A15_CODES = [
     'HFS_WORKFLOW_CONTEXT',
     'CI_STANDARD',
     'CI_SECRET_SEALED', 'APP_SECRET_IN_CI', 'CI_DECLARATION_DRIFT',
+    'STACKS_LOCAL_CONFIG_INVALID', 'STACKS_DEV_UNDECLARED', 'STACKS_RUNBOOK_DOCKER_COMMAND',
     'BACKUP_PROOF_MISSING', 'BACKUP_UNDECLARED', 'BE_APP_BOOT_PROOF_MISSING', 'BOOT_PROOF_TIMEOUT', 'BE_APP_ENV_REQUIRED', 'BE_APP_MODULE_LIST_INLINE', 'BE_LITE_PROOF_LANE_MISSING', 'DB_ARCHIVE_MUTATED', 'DB_BASELINE_SHAPE', 'DB_EXTENSION_ALLOWED', 'DB_MIGRATION_DESTRUCTIVE', 'DB_PGMQ_DECLARED', 'DB_VAULT_WRITE', 'ENV_DUPLICATE', 'ENV_EXAMPLE_DRIFT', 'ENV_PUBLIC_SEALED', 'ENV_REQUIRED_UNSET', 'ENV_SEALED_UNREAD', 'ENV_VALUE_SHAPE', 'FE_STACK_CORE_MISSING', 'FE_STACK_UNLISTED', 'HFS_AGE_KEY_CUSTODY', 'HFS_APP_LEXICON', 'HFS_APP_WORKFLOW_TRIGGER', 'HFS_ASSET_KIND', 'HFS_ASSET_OVERSIZE', 'HFS_AUDIT_STEP_MISSING', 'HFS_AUTH_COOKIE_DOMAIN_MISSING', 'HFS_CANON_COPY_DRIFT', 'HFS_CI_TOOL_INSTALL', 'HFS_COVERAGE_BELOW', 'HFS_DB_DEPLOY_UNGUARDED', 'HFS_DEPENDABOT_MISSING', 'HFS_DEPLOY_COMPOSE_ON_VPS', 'HFS_DEPLOY_NO_LOGIC', 'HFS_DEPLOY_SCHEDULER', 'HFS_DEPLOY_WORKFLOW', 'HFS_DOC_COMMAND_UNKNOWN', 'HFS_DOC_ENV_UNKNOWN', 'HFS_DOC_PATH_MISSING', 'HFS_DOC_RULE_UNKNOWN', 'HFS_FEATURE_FILE_BUDGET', 'HFS_HOST_CRON', 'HFS_RELEASE_TAG_MISMATCH', 'HFS_SBOM_MISSING', 'HFS_SCHEDULE_UNDECLARED', 'HFS_SCRIPT_PLAINTEXT_LOAD', 'HFS_SCRIPT_XTRACE', 'HFS_SECRET_OUTSIDE_ENC', 'HFS_SECRET_PLAINTEXT_FILE', 'HFS_SEED_PII', 'HFS_UNUSED_SYMBOL', 'HFS_WORKFLOW_PIN', 'STACKS_DEPLOY_CONFIG_INVALID', 'STACKS_DNS_UNDECLARED', 'STACKS_HEALTHCHECK_MISSING', 'STACKS_HOST_UNROUTED', 'STACKS_INGRESS_UNDECLARED', 'STACKS_INGRESS_UNKNOWN', 'STACKS_LITE_REDIS_PERSISTENCE', 'STACKS_LITE_SELFHOSTED_DB', 'STACKS_MODEL_UNAVAILABLE', 'STACKS_PLACEMENT_MISSING', 'STACKS_PORT_PUBLISHED', 'STACKS_REALTIME_SCALED', 'STACKS_RELEASE_UNDECLARED', 'STACKS_SECOND_INGRESS', 'STACKS_SECRET_ENV_LITERAL', 'STACKS_SECRET_NOT_EXTERNAL', 'STACKS_SECRET_UNVERSIONED', 'STACKS_SIDECAR_DB_UNSUPPORTED', 'STACKS_SIDECAR_VOLUME_UNDECLARED', 'STACKS_TLS_UNDECLARED', 'STACKS_UPDATE_POLICY_MISSING', 'STACK_TOOLING_REIMPLEMENTED',
     // codes-end
 ];
@@ -87,6 +90,8 @@ export const FINDERS = [
     stacksLiteBackingFindings,
     stackToolingFindings,
     stacksDeployFindings,
+    stacksLocalFindings,
+    stacksServiceImageFindings,
     stacksAuthCookieDomainFindings,
     ciCustodyFindings,
     // finders-end

package/runtime/scripts/hfs/rules/stacks-local.d.mts

@@ -0,0 +1,7 @@
+import type { Repo } from './rule-types.mjs';
+/** Findings of the dev environments of the app root. */
+export declare function stacksLocalFindings({ repoRoot, repo, isRoot }: {
+    repoRoot: string;
+    repo: Repo;
+    isRoot: boolean;
+}): import("./rule-types.mjs").Finding[];

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

@@ -0,0 +1,71 @@
+// stacks-local.mjs - R372 and R373: the dev environment of an app is declared runnable and its runbook names the harness verb.
+//   R372 STACKS_LOCAL_CONFIG_INVALID  every docker-compose environment carries a `local` block that the dev verbs of `starci app stack`
+//                                      normalise (scripts/hfs/stack-local-config.mjs), and its compose services exist in the compose files;
+//        STACKS_DEV_UNDECLARED         a lite app declares at least one docker-compose environment (the dev kind of PROJECT-STACKS-3).
+//   R373 STACKS_RUNBOOK_DOCKER_COMMAND the runbook of a docker-compose environment names `starci app stack up --env <env>` and carries no
+//                                      `docker build|run|compose|create|start|stop|pull|push` or `docker stack deploy` command (rules.md rule 8).
+import fs from 'node:fs';
+import path from 'node:path';
+import { isPlainObject as plain } from '../../../engine/plain-object.mjs';
+import { findStackDeclaration, readDeclaration, STACK_ROOT } from '../../lib/stack-declaration.mjs';
+import { normalizeLocal } from '../stack-local-config.mjs';
+import { found, readJson } from './read.mjs';
+const DECLARATION = `${STACK_ROOT}/application-stacks.yaml`;
+const ENV_NAME = /^[a-z0-9][a-z0-9-]*$/u;
+const DOCKER_COMMAND = /^\s*(?:[$>]\s*)?(?:\w+=\S+\s+)*docker(?:-compose)?\s+(?:build|buildx|run|compose|create|start|stop|rm|pull|push|stack\s+deploy|stack\s+rm|service)\b/u;
+const mapping = (value) => (plain(value) ? value : {});
+function composeServices(envDir, spec) {
+    const names = new Set();
+    for (const relative of Array.isArray(spec.composeFiles) ? spec.composeFiles : []) {
+        if (typeof relative !== 'string' || path.isAbsolute(relative) || relative.split(/[\\/]/u).includes('..'))
+            continue;
+        for (const name of Object.keys(mapping(readDeclaration(path.join(envDir, relative)).doc?.services)))
+            names.add(name);
+    }
+    return names;
+}
+function localFindings({ repoRoot, project, environment, spec }) {
+    const at = `environments.${environment}.local`;
+    if (spec.local === undefined)
+        return [found('STACKS_LOCAL_CONFIG_INVALID', DECLARATION, `environments.${environment} runs docker-compose and declares no local block: declare the ports, services, processes and probes \`starci app stack up --env ${environment}\` runs`)];
+    const { config, problems } = normalizeLocal(spec.local, { project, env: environment });
+    const findings = problems.map((problem) => found('STACKS_LOCAL_CONFIG_INVALID', DECLARATION, `${at}.${problem.at}: ${problem.message}`));
+    if (config) {
+        const services = composeServices(path.join(repoRoot, STACK_ROOT, environment), spec);
+        for (const service of config.services)
+            if (!services.has(service.name))
+                findings.push(found('STACKS_LOCAL_CONFIG_INVALID', DECLARATION, `${at}.services: ${service.name} is not a service of the compose files of ${environment}`));
+    }
+    return findings;
+}
+function runbookFindings({ repoRoot, environment, spec }) {
+    const relative = typeof spec.runbook === 'string' ? spec.runbook : 'README.md';
+    const file = path.join(repoRoot, STACK_ROOT, environment, relative);
+    const display = path.relative(repoRoot, file).split(path.sep).join('/');
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const findings = text.split(/\r?\n/u).map((line, index) => ({ line, index })).filter(({ line }) => DOCKER_COMMAND.test(line) || /`docker\s+(?:build|run|compose|create|start|stop|pull|push|stack)\b/u.test(line))
+        .map(({ index }) => found('STACKS_RUNBOOK_DOCKER_COMMAND', `${display}:${index + 1}`, `the runbook of ${environment} carries a docker command; Docker is run by the harness: name \`starci app stack up --env ${environment}\` instead`));
+    if (!text.includes(`starci app stack up --env ${environment}`))
+        findings.push(found('STACKS_RUNBOOK_DOCKER_COMMAND', display, `the runbook of ${environment} does not name \`starci app stack up --env ${environment}\`, the one command that brings the environment up`));
+    return findings;
+}
+/** Findings of the dev environments of the app root. */
+export function stacksLocalFindings({ repoRoot, repo, isRoot }) {
+    if (repo?.kind !== 'app' || !['lite', 'full'].some((value) => value === repo.edition) || isRoot === false)
+        return [];
+    const { doc } = findStackDeclaration(repoRoot);
+    if (!doc)
+        return [];
+    const project = String(readJson(repoRoot, 'hfs.json')?.project ?? 'app');
+    const judged = Object.entries(mapping(mapping(doc).environments)).filter(([environment, spec]) => ENV_NAME.test(environment) && plain(spec) && spec.runtime === 'docker-compose');
+    const findings = judged.flatMap(([environment, spec]) => [...localFindings({ repoRoot, project, environment, spec }), ...runbookFindings({ repoRoot, environment, spec })]);
+    if (repo.edition === 'lite' && judged.length === 0)
+        findings.push(found('STACKS_DEV_UNDECLARED', DECLARATION, 'a lite app declares its dev environment: an environment with runtime docker-compose and a local block, run by `starci app stack up --env dev` (PROJECT-STACKS-3, PROJECT-STACKS-6)'));
+    return findings;
+}

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

@@ -99,6 +99,9 @@ function liteEnvironmentFindings({ doc, environments, deployments }) {
     for (const [environment, spec] of Object.entries(environments)) {
         if (!Array.isArray(spec?.composeFiles) || !spec.composeFiles.length)
             continue;
+        // The dev kind (PROJECT-STACKS-3): docker-compose sources under infra/compose/ with the local block `starci app stack up` runs; judged by R372.
+        if (spec.runtime === 'docker-compose' && spec.local !== undefined && spec.composeFiles.every((file) => typeof file === 'string' && file.startsWith('infra/compose/')))
+            continue;
         if (spec.runtime !== 'docker-swarm' || spec.composeFiles.some((file) => typeof file !== 'string' || !file.startsWith('infra/swarm/')))
             findings.push(found(CODE, DECLARATION, `${DECLARATION}: environments.${environment} lite delivery must use runtime: docker-swarm and infra/swarm sources`));
     }
@@ -111,11 +114,13 @@ function undeclaredSwarmFindings(deployments, environments, sources) {
         return found(CODE, file, `${file}: Swarm deployment ${reason}`);
     });
 }
+/** The component ids a docker-swarm environment binds: the only ones the lite refusal of backing images judges (a dev compose environment runs its own MinIO, Redis and agent runtime). */
+const swarmBoundComponents = (environments) => new Set(Object.values(environments).filter((spec) => spec?.runtime === 'docker-swarm').flatMap((spec) => Object.keys(mapping(spec.components))));
 /** Declared Swarm sources are checked for both editions; lite additionally refuses local managed backing images. */
 export function stacksRuntimeFindings({ repoRoot, files, doc, edition = 'full' }) {
     const findings = [], lite = edition === 'lite', components = mapping(doc?.components), environments = mapping(doc?.environments);
     const deployments = swarmDeploymentFiles(repoRoot, files), sources = new Set();
-    findings.push(...swarmInventoryIssues({ components, lite }).map((issue) => issueFinding(DECLARATION, issue)));
+    findings.push(...swarmInventoryIssues({ components, lite, swarm: swarmBoundComponents(environments) }).map((issue) => issueFinding(DECLARATION, issue)));
     if (lite)
         findings.push(...liteEnvironmentFindings({ doc, environments, deployments }));
     for (const [environment, entry] of Object.entries(environments)) {

package/runtime/scripts/hfs/rules/stacks-service-images.d.mts

@@ -0,0 +1,12 @@
+import { found } from './read.mjs';
+import type { Repo } from './rule-types.mjs';
+type Finding = ReturnType<typeof found>;
+/** The fork repositories the harness owns, by service name. */
+export declare function forkImages(): Record<string, string>;
+/** Findings of R374 for the app root. */
+export declare function stacksServiceImageFindings({ repoRoot, repo, isRoot }: {
+    repoRoot: string;
+    repo: Repo;
+    isRoot: boolean;
+}): Finding[];
+export {};

package/runtime/scripts/hfs/rules/stacks-service-images.mjs

@@ -0,0 +1,120 @@
+// stacks-service-images.mjs - R374: a customised service runs from an image the app builds, never from an upstream image with code mounted into it.
+//   STACKS_CODE_BIND_MOUNT      a stack or compose file bind-mounts code, a script, a plugin or a writable repository path into a service container.
+//                               Allowed: a named volume, a secret or config grant (not volumes), a bind under the data root (`${data}`, `${STACK_DATA_DIR}`) or a least grant (`${STACK_GRANT_<NAME>}`),
+//                               the docker socket read-only, and a read-only plain data file (json, yaml, toml, conf, ini, properties, txt, pem, crt, csv).
+//   STACKS_IMAGE_BASE_UNPINNED  a Dockerfile of `.starcistacks/images/<name>/` has a FROM that is not digest-pinned.
+//   STACKS_IMAGE_BASE_NOT_FORK  the image folder of a service the harness owns a fork image for (knowledge/hfs/fork-images.yaml) does not end FROM that fork.
+//   STACKS_IMAGE_ENV_DIVERGES   a service that has an image folder runs a literal third-party image in some environment: every environment runs the
+//                               image built from the folder (compose `build.context`, or a project-owned or variable image reference), so dev and production share it.
+import fs from 'node:fs';
+import path from 'node:path';
+import { isPlainObject as plain } from '../../../engine/plain-object.mjs';
+import { parseYaml } from '../../../engine/yaml.mjs';
+import { findStackDeclaration, readDeclaration, STACK_ROOT } from '../../lib/stack-declaration.mjs';
+import { found, readJson } from './read.mjs';
+const FORKS = new URL('../../../knowledge/hfs/fork-images.yaml', import.meta.url);
+const ENV_NAME = /^[a-z0-9][a-z0-9-]*$/u;
+const DATA_ROOT = /^(?:\$\{(?:data|STACK_DATA_DIR|STACK_GRANT_[A-Z0-9_]+)\}|\$(?:data|STACK_DATA_DIR|STACK_GRANT_[A-Z0-9_]+))(?:[\\/]|$)/u;
+const DATA_FILE = /\.(?:json|ya?ml|toml|conf|cnf|cfg|ini|properties|txt|pem|crt|csv)$/iu;
+const SOCKET = '/var/run/docker.sock';
+const mapping = (value) => (plain(value) ? value : {});
+/** The fork repositories the harness owns, by service name. */
+export function forkImages() {
+    return mapping(mapping(parseYaml(fs.readFileSync(FORKS, 'utf8'))).images);
+}
+/** One volume entry as { source, readOnly } when it is a bind mount (a host path), else null. */
+function bindOf(entry) {
+    if (typeof entry === 'string') {
+        const [source = '', , mode = ''] = entry.split(':');
+        if (!/^(?:\.|\/|~|\$\{|\$[A-Za-z])/u.test(source))
+            return null;
+        return { source, readOnly: mode.split(',').includes('ro') };
+    }
+    const long = mapping(entry);
+    if (long.type !== 'bind' || typeof long.source !== 'string')
+        return null;
+    return { source: long.source, readOnly: long.read_only === true };
+}
+/** Whether a bind mount is a data volume or plain read-only config data, the line R374 draws. */
+const allowedBind = ({ source, readOnly }) => DATA_ROOT.test(source) || (readOnly && (source === SOCKET || DATA_FILE.test(source)));
+const baseOf = (reference) => reference.replace(/@sha256:[0-9a-f]+$/iu, '').replace(/:[^/:]+$/u, '');
+function bindFindings(display, environment, services) {
+    return Object.entries(services).flatMap(([name, service]) => (Array.isArray(mapping(service).volumes) ? mapping(service).volumes : [])
+        .map(bindOf).filter((bind) => bind !== null && !allowedBind(bind))
+        .map((bind) => found('STACKS_CODE_BIND_MOUNT', display, `${environment}: service ${name} bind-mounts ${bind.source}; code, plugins and scripts are baked into an image built from .starcistacks/images/${name}/ (FROM the pinned base, or the harness fork image), and only data volumes, secrets and read-only plain config data are mounted`)));
+}
+function dockerfileFindings(repoRoot, forks) {
+    const images = path.join(repoRoot, STACK_ROOT, 'images');
+    if (!fs.existsSync(images))
+        return [];
+    return fs.readdirSync(images, { withFileTypes: true }).filter((entry) => entry.isDirectory()).flatMap((entry) => {
+        const display = `${STACK_ROOT}/images/${entry.name}/Dockerfile`;
+        let text;
+        try {
+            text = fs.readFileSync(path.join(images, entry.name, 'Dockerfile'), 'utf8');
+        }
+        catch {
+            return [];
+        }
+        const stages = new Set();
+        const bases = [];
+        const findings = [];
+        for (const line of text.split(/\r?\n/u)) {
+            const from = /^\s*FROM\s+(?:--platform=\S+\s+)?(\S+)(?:\s+AS\s+(\S+))?/iu.exec(line);
+            if (!from)
+                continue;
+            const ref = from[1];
+            if (from[2])
+                stages.add(from[2].toLowerCase());
+            if (stages.has(ref.toLowerCase()) || ref === 'scratch')
+                continue;
+            bases.push(ref);
+            if (!/@sha256:[0-9a-f]{64}/iu.test(ref))
+                findings.push(found('STACKS_IMAGE_BASE_UNPINNED', display, `FROM ${ref} is not pinned by digest (name@sha256:...)`));
+        }
+        const fork = forks[entry.name];
+        const last = bases.at(-1);
+        if (fork !== undefined && last !== undefined && baseOf(last) !== fork)
+            findings.push(found('STACKS_IMAGE_BASE_NOT_FORK', display, `the harness owns the StarCi fork image ${fork} for ${entry.name}; the final stage must be FROM ${fork}@sha256:..., not ${baseOf(last)}`));
+        return findings;
+    });
+}
+/** Whether a service's image/build is the one built from its image folder, or a project-owned or variable reference. */
+function builtFromFolder(service, name, project) {
+    const build = service.build;
+    const context = typeof build === 'string' ? build : typeof mapping(build).context === 'string' ? String(mapping(build).context) : '';
+    if (context !== '' && context.replaceAll('\\', '/').includes(`images/${name}`))
+        return true;
+    const image = typeof service.image === 'string' ? service.image : '';
+    return image.includes('${') || image.startsWith(`${project}/`) || image.startsWith(`${project}-`) || image.includes(`/${project}/`);
+}
+/** Findings of R374 for the app root. */
+export function stacksServiceImageFindings({ repoRoot, repo, isRoot }) {
+    if (repo?.kind !== 'app' || !['lite', 'full'].some((value) => value === repo.edition) || isRoot === false)
+        return [];
+    const { doc } = findStackDeclaration(repoRoot);
+    if (!doc)
+        return [];
+    const project = String(readJson(repoRoot, 'hfs.json')?.project ?? 'app');
+    const folders = path.join(repoRoot, STACK_ROOT, 'images');
+    const withFolder = new Set(fs.existsSync(folders) ? fs.readdirSync(folders, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name) : []);
+    const findings = dockerfileFindings(repoRoot, forkImages());
+    for (const [environment, spec] of Object.entries(mapping(mapping(doc).environments))) {
+        if (!ENV_NAME.test(environment) || !plain(spec))
+            continue;
+        const files = Array.isArray(spec.composeFiles) ? spec.composeFiles : [];
+        for (const relative of files) {
+            if (typeof relative !== 'string' || path.isAbsolute(relative) || relative.split(/[\\/]/u).includes('..'))
+                continue;
+            const file = path.join(repoRoot, STACK_ROOT, environment, relative);
+            const display = path.relative(repoRoot, file).split(path.sep).join('/');
+            const services = mapping(readDeclaration(file).doc?.services);
+            findings.push(...bindFindings(display, environment, services));
+            for (const [name, service] of Object.entries(services)) {
+                if (withFolder.has(name) && !builtFromFolder(mapping(service), name, project))
+                    findings.push(found('STACKS_IMAGE_ENV_DIVERGES', display, `${environment}: service ${name} has an image folder but runs ${String(mapping(service).image)}; every environment runs the image built from .starcistacks/images/${name}/ so dev and production share one image`));
+            }
+        }
+    }
+    return findings;
+}

package/runtime/scripts/hfs/secret-dev-init.d.mts

@@ -0,0 +1,11 @@
+import type { SecretSops } from "./secret-sops.mjs";
+import type { CustodyGenerator } from "./stack-local-config.mjs";
+/** One generated value (or a private/public pair) by its kind; the `password` kind is URL- and SQL-safe. */
+export declare function generateValues(entry: CustodyGenerator, random?: (bytes: number) => Buffer): Record<string, string>;
+/** Seals the missing dev values of `environment`; a dry run unless `execute`. Returns the exit code. */
+export declare function seedDevCustody(repoRoot: string, environment: string, { execute, sops, stdout, random }: {
+    execute: boolean;
+    sops: () => SecretSops;
+    stdout: (text: string) => unknown;
+    random?: (bytes: number) => Buffer;
+}): number;

package/runtime/scripts/hfs/secret-dev-init.mjs

@@ -0,0 +1,79 @@
+// secret-dev-init.mjs - `starci app secret init --env <dev env> [--execute]`: creates the dev-only values the environment's `local.custody`
+// declares (PROJECT-STACKS-5: sealed only, owner-armed, created once, never replaced). It refuses an environment that is not a docker-compose
+// dev environment (vps and production never get generated values), skips a key its member already holds, and refuses a half-present pair
+// instead of minting a replacement. Values are generated in memory and sealed in one write per member; names are all it prints.
+import fs from "node:fs";
+import { generateKeyPairSync, randomBytes, randomUUID } from "node:crypto";
+import { envelopeOf } from "./secret-document.mjs";
+import { SecretError } from "./secret-errors.mjs";
+import { fileOf, secretsDirectory, writeSecret } from "./secret-store.mjs";
+import { declareKeys } from "./secret-standard.mjs";
+import { isLocalEnvironment, loadLocalConfig } from "../../../stack/local-config.mjs";
+/** One generated value (or a private/public pair) by its kind; the `password` kind is URL- and SQL-safe. */
+export function generateValues(entry, random = randomBytes) {
+    if (entry.kind === "hex")
+        return { [entry.key]: random(entry.bytes).toString("hex") };
+    if (entry.kind === "base64")
+        return { [entry.key]: random(entry.bytes).toString("base64") };
+    if (entry.kind === "password")
+        return { [entry.key]: random(entry.bytes).toString("base64url") };
+    if (entry.kind === "uuid")
+        return { [entry.key]: randomUUID() };
+    if (entry.kind === "rsa-pem" || entry.kind === "ec-pem" || entry.kind === "ed25519-pem") {
+        const pair = entry.kind === "rsa-pem"
+            ? generateKeyPairSync("rsa", { modulusLength: 2048, privateKeyEncoding: { type: "pkcs8", format: "pem" }, publicKeyEncoding: { type: "spki", format: "pem" } })
+            : entry.kind === "ec-pem"
+                ? generateKeyPairSync("ec", { namedCurve: "P-256", privateKeyEncoding: { type: "pkcs8", format: "pem" }, publicKeyEncoding: { type: "spki", format: "pem" } })
+                : generateKeyPairSync("ed25519", { privateKeyEncoding: { type: "pkcs8", format: "pem" }, publicKeyEncoding: { type: "spki", format: "pem" } });
+        return { [entry.key]: pair.privateKey, ...(entry.publicKey ? { [entry.publicKey]: pair.publicKey } : {}) };
+    }
+    throw new SecretError(`the generator ${entry.kind} is unknown`);
+}
+/** Seals the missing dev values of `environment`; a dry run unless `execute`. Returns the exit code. */
+export function seedDevCustody(repoRoot, environment, { execute, sops, stdout, random = randomBytes }) {
+    if (!isLocalEnvironment(repoRoot, environment))
+        throw new SecretError(`secret init --env ${environment}: only a docker-compose dev environment gets generated values; a vps or production value is set by the owner with secret set (PROJECT-STACKS-5)`);
+    const local = loadLocalConfig({ repoRoot, env: environment });
+    if (local.custody.length === 0)
+        throw new SecretError(`environment ${environment} declares no local.custody: nothing to generate; the owner seals its values with secret set`);
+    const directory = secretsDirectory(repoRoot, environment);
+    const byMember = new Map();
+    for (const entry of local.custody)
+        byMember.set(entry.member, [...(byMember.get(entry.member) ?? []), entry]);
+    const writes = [];
+    for (const [member, entries] of byMember) {
+        const file = fileOf(directory, member);
+        const held = fs.existsSync(file) ? envelopeOf(fs.readFileSync(file, "utf8")).keys : [];
+        const values = {};
+        for (const entry of entries) {
+            const names = [entry.key, ...(entry.publicKey ? [entry.publicKey] : [])];
+            const have = names.filter((name) => held.includes(name));
+            if (have.length === names.length) {
+                stdout(`kept ${environment}/${member} ${entry.key} (already sealed, never replaced)\n`);
+                continue;
+            }
+            if (have.length > 0)
+                throw new SecretError(`${environment}/${member} holds ${have.join(", ")} but not the rest of its pair ${names.join(", ")}: a replacement is never minted for an existing sealed value; the owner removes the pair with secret unset and runs init again`);
+            Object.assign(values, generateValues(entry, random));
+        }
+        if (Object.keys(values).length)
+            writes.push({ file, member, values });
+    }
+    for (const write of writes) {
+        const names = Object.keys(write.values);
+        if (!execute) {
+            stdout(`would seal ${environment}/${write.member} (${names.join(", ")})\n`);
+            continue;
+        }
+        writeSecret({ file: write.file, values: write.values, age: [], sops: sops() });
+        stdout(`sealed ${environment}/${write.member} (${names.join(", ")})\n`);
+        const declaration = declareKeys(repoRoot, environment, write.member, names);
+        if (declaration.declared.length)
+            stdout(`declared ${declaration.declared.join(", ")} in environments.${environment}.secrets of application-stacks.yaml\n`);
+    }
+    if (writes.length === 0)
+        stdout("nothing to create: every declared dev value is sealed\n");
+    else if (!execute)
+        stdout("dry run: nothing was written; arm it with --execute (the owner's yes)\n");
+    return 0;
+}

package/runtime/scripts/hfs/secret.mjs

@@ -24,6 +24,7 @@ import { setValues } from "./secret-prompt.mjs";
 import { stackContext } from "../../../stack/context.mjs";
 import { StackError } from "../../../stack/errors.mjs";
 import { serverKey } from "../../../stack/server-key.mjs";
+import { seedDevCustody } from "./secret-dev-init.mjs";
 export { envelopeOf, formatOf, plaintextOf } from "./secret-document.mjs";
 export { setSecretValues } from "./secret-store.mjs";
 /** The actions of `starci app secret`, in usage order. */
@@ -76,7 +77,7 @@ function parse(argv) {
 /** The operands and flags of one secret action, as the usage of `starci app secret` prints them. */
 export function secretUsage(verb) {
     if (verb === "init")
-        return "";
+        return "[--env <dev env> [--execute]]";
     if (verb === "set")
         return "--env <env> <slug> <KEY> [KEY ...] [--generate <bytes>] [--from-file KEY=path ...]";
     if (verb === "get")
@@ -100,8 +101,8 @@ export function secretUsage(verb) {
     return "--env <env>";
 }
 function editOptionsFor(verb, opts) {
-    if (opts.execute !== undefined && !EDIT_VERBS.has(verb) && !MOVE_VERBS.has(verb) && verb !== "server-key" && verb !== "recipients")
-        throw new SecretError("--execute is only valid for unset, rename, remove, recipients, migrate, split and server-key");
+    if (opts.execute !== undefined && !EDIT_VERBS.has(verb) && !MOVE_VERBS.has(verb) && verb !== "server-key" && verb !== "recipients" && verb !== "init")
+        throw new SecretError("--execute is only valid for init --env, unset, rename, remove, recipients, migrate, split and server-key");
     if (opts.execute !== undefined && verb === "recipients" && !opts.add && !opts.remove)
         throw new SecretError("--execute is only valid for recipients with --add or --remove");
     if ((opts.rotate !== undefined || opts.backup !== undefined || opts.restore !== undefined) && verb !== "server-key")
@@ -128,8 +129,8 @@ function outputOptionsFor(verb, opts) {
 }
 /** The environment leads the operands (`--env <env> <slug> ...` is checked and read as `<env> <slug> ...`); init takes none, audit may name one. */
 function environmentOf(verb, opts) {
-    if (verb === "init" && opts.env !== undefined)
-        throw new SecretError("--env is not valid for init");
+    if (verb === "init" && opts.env === undefined && opts.execute !== undefined)
+        throw new SecretError("--execute is only valid for init --env <dev env>");
     if (verb !== "init" && verb !== "audit" && opts.env === undefined)
         throw new SecretError(`usage: starci app secret ${verb} ${secretUsage(verb)}`);
     if (verb === "audit" && opts.positional.length)
@@ -141,7 +142,7 @@ function optionsFor(verb, opts) {
     environmentOf(verb, opts);
     const count = opts.positional.length;
     const bounds = {
-        init: [0, 0],
+        init: [0, 1],
         list: [1, 1],
         materialize: [1, 1],
         verify: [1, 1],
@@ -253,10 +254,12 @@ export async function secretMain(argv, { stdout = (s) => process.stdout.write(s)
     const [verb, ...rest] = argv;
     try {
         if (!VERBS.has(verb))
-            throw new SecretError("usage: starci app secret init | set --env <env> <slug> <KEY> [KEY ...] | get --env <env> <slug> [KEY] --to-file | unset --env <env> <slug> <KEY> | rename --env <env> <slug> <OLD> <NEW> | remove --env <env> <slug> | materialize --env <env> | list --env <env> | verify --env <env> | recipients --env <env> [--add|--remove ...] [--execute] | migrate --env <env> <slug> [--to <slug>] [--into-existing] | split --env <env> <slug> [--group KEY=member] [--group-file <yaml>] [--into-existing] | audit [--env <env>] | server-key --env <env> [--rotate | --backup github | --restore github] [--execute]");
+            throw new SecretError("usage: starci app secret init [--env <dev env> [--execute]] | set --env <env> <slug> <KEY> [KEY ...] | get --env <env> <slug> [KEY] --to-file | unset --env <env> <slug> <KEY> | rename --env <env> <slug> <OLD> <NEW> | remove --env <env> <slug> | materialize --env <env> | list --env <env> | verify --env <env> | recipients --env <env> [--add|--remove ...] [--execute] | migrate --env <env> <slug> [--to <slug>] [--into-existing] | split --env <env> <slug> [--group KEY=member] [--group-file <yaml>] [--into-existing] | audit [--env <env>] | server-key --env <env> [--rotate | --backup github | --restore github] [--execute]");
         const opts = parse(rest);
         optionsFor(verb, opts);
         const repoRoot = path.resolve(cwd, opts.cwd ?? ".");
+        if (verb === "init" && opts.env !== undefined)
+            return seedDevCustody(repoRoot, opts.env, { execute: opts.execute === true, sops: () => sops ?? defaultSops(env, repoRoot, platform, tools, hostIdentity), stdout, random });
         if (verb === "init")
             return publicStorage(() => initializeSecrets(repoRoot, { env, platform, tools, stdout, host: hostIdentity }));
         if (verb === "audit")

package/runtime/scripts/hfs/slots.mjs

@@ -232,7 +232,7 @@ export function readRepoDeclaration(manifest, repoRoot) {
 function createScopeResolver(manifest, repo) {
     const profile = repo.profile;
     const edition = repo.edition ?? 'full';
-    const slots = manifest.slots.filter((s) => s.profiles.includes(profile) && slotInEdition(manifest, s, edition)).map((s) => effectiveSlot(s, profile, edition));
+    const slots = manifest.slots.filter((s) => s.managedOnly !== true && s.profiles.includes(profile) && slotInEdition(manifest, s, edition)).map((s) => effectiveSlot(s, profile, edition));
     const scope = { manifest, repo, profile, slots, byId: new Map(slots.map((s) => [s.id, s])), variants: slots.flatMap(variantsOf), appKind: new Map(repo.apps.map((a) => [a.name, a.kind])) };
     const classifyPath = (input) => classifyIn(scope, input);
     /** tracked | ignored | external for the slot owning `p`, or null when no slot owns it. */

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

@@ -0,0 +1,101 @@
+import type { StackProblem } from './stack-config-kit.mjs';
+export declare const LOCAL_CONFIG_CODE = "STACKS_LOCAL_CONFIG";
+/** The generators `starci app secret init --env <env>` knows (PROJECT-STACKS-5: dev-only values, created once, never replaced). */
+export declare const GENERATORS: readonly string[];
+/** A key of a sealed member of the environment. */
+export interface CustodyRef {
+    member: string;
+    key: string;
+}
+/** A command the verbs run: an argv list (never a shell line), run from `cwd` (app-root relative). */
+export interface LocalCommand {
+    name: string;
+    argv: string[];
+    cwd: string;
+    heavy: 'install' | 'build' | 'none';
+    skipIfExists: string | null;
+    env: Record<string, string>;
+    files: string[];
+    /** Seed only: `migrate` runs it once the database is migrated, `ready` once the processes answer (a seed that signs up through the api). */
+    after: 'migrate' | 'ready';
+}
+/** A compose service the environment starts and how its readiness is observed. */
+export interface LocalService {
+    name: string;
+    wait: 'healthy' | 'started' | 'tcp';
+    port: string | null;
+}
+/** A native app process. */
+export interface LocalProcess extends LocalCommand {
+    port: string | null;
+    health: HttpProbe | null;
+}
+/** One HTTP probe: the readiness of a process, a `ready` row or a `verify` row. */
+export interface HttpProbe {
+    name: string;
+    url: string;
+    method: string;
+    status: number;
+    contains: string | null;
+}
+/** The per-environment database: its compose service, its own login role and where the app reads its URL. */
+export interface LocalDatabase {
+    service: string;
+    port: string;
+    name: string;
+    role: string;
+    urlEnv: string;
+    urlAs: 'env' | 'file';
+    adminUser: string;
+    password: CustodyRef;
+    adminPassword: CustodyRef;
+    appRole: string | null;
+    appPassword: CustodyRef | null;
+}
+/** One dev-only value the owner-armed `secret init` creates once. */
+export interface CustodyGenerator extends CustodyRef {
+    kind: string;
+    bytes: number;
+    publicKey: string | null;
+}
+/** The normalised `local` block of one environment. */
+export interface LocalBlock {
+    project: string;
+    ports: Record<string, number>;
+    services: LocalService[];
+    database: LocalDatabase | null;
+    composeEnv: Array<CustodyRef & {
+        name: string;
+    }>;
+    /** Least grants: the keys one compose service may read, mounted from `STACK_GRANT_<NAME>` (a directory holding only those keys). */
+    grants: Array<{
+        name: string;
+        keys: string[];
+    }>;
+    /** Data directories under the state base (`${data}/<name>`, `STACK_DATA_DIR`), created by `up` before anything starts: bind mounts and file stores of native processes. */
+    dirs: string[];
+    custody: CustodyGenerator[];
+    setup: LocalCommand[];
+    seed: LocalCommand[];
+    processes: LocalProcess[];
+    ready: HttpProbe[];
+    verify: HttpProbe[];
+    origins: Array<{
+        name: string;
+        url: string;
+    }>;
+    resources: {
+        diskGb: number;
+        ramMb: number;
+    };
+}
+/** The normalised `local` block, or the problems that stop it. `project` and `env` name the defaults (`<project>-<env>`, the role). */
+export declare function normalizeLocal(raw: unknown, { project, env }: {
+    project: string;
+    env: string;
+}): {
+    config: LocalBlock | null;
+    problems: StackProblem[];
+};
+/** Replaces `${port.<name>}` with the chosen host port. */
+export declare const expandPorts: (value: string, ports: Readonly<Record<string, number>>) => string;