@starci/hfs 5.1.0 → 5.3.0

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

@@ -1,6 +1,6 @@
 // monorepo.mjs - every product is a monorepo, even a single app: the app root holds one package.json and lockfile whose npm
 // workspaces are the fe apps and packages (turbo runs their tasks), and the back end is a Nest monorepo of be/apps/<app>.
-//   HFS_MONO_WORKSPACES          the root package.json: `workspaces` exactly fe/apps/* and fe/packages/*, `packageManager` npm at an
+//   HFS_MONO_WORKSPACES          the root package.json: `workspaces` exactly fe/apps/* and fe/packages/* (and packages/* once the app tracks a root workspace package, slot app.packages), `packageManager` npm at an
 //                                exact version, turbo a root devDependency (its version is the canon pin); turbo.json is app.task-graph
 //   HFS_MONO_FE_WORKSPACE        every fe app's package.json is @<project>/<app>, private, with exactly the workspace scripts; every
 //                                fe package's package.json is private with build and typecheck scripts and the workspace lint
@@ -22,6 +22,10 @@ const MONO_NEST_PROJECTS = 'HFS_MONO_NEST_PROJECTS';
 const MONO_WORKSPACE_DEP = 'HFS_MONO_WORKSPACE_DEP';
 /** The npm workspaces of every app, in this order. */
 export const WORKSPACES = Object.freeze(['fe/apps/*', 'fe/packages/*']);
+/** The workspace of the app's own root packages (slot app.packages: packages/agent-sdk, packages/module-<name>), added after the fe ones once one is tracked. */
+export const ROOT_PACKAGES_WORKSPACE = 'packages/*';
+/** The workspaces the tracked tree `files` calls for: the fe ones, then `packages/*` when a root package tracks its package.json. */
+export const workspacesFor = (files) => (files.some((file) => /^packages\/[^/]+\/package\.json$/.test(file)) ? [...WORKSPACES, ROOT_PACKAGES_WORKSPACE] : WORKSPACES);
 /** The scripts of every fe app workspace, exactly: turbo runs build, dev and typecheck; start serves a build. The lint is the root's (`starci app check --gate lint`), never a workspace script. */
 export const FE_APP_SCRIPTS = Object.freeze({ build: 'next build', dev: 'next dev', start: 'next start', typecheck: 'tsc --noEmit' });
 /** The scripts every fe package workspace has (its build and typecheck commands are its own); it has no lint script. */
@@ -49,13 +53,14 @@ function workspacesOf(files) {
     return [...folders].sort(byCodeUnit);
 }
 /** R143: the root package.json declares the workspaces, the package manager and turbo. */
-function rootFindings(repoRoot) {
+function rootFindings(repoRoot, files) {
     const pkg = readJson(repoRoot, MANIFEST);
     if (!pkg)
         return [];
     const findings = [];
-    if (!sameList(pkg.workspaces, WORKSPACES))
-        findings.push(found(MONO_WORKSPACES, MANIFEST, `${MANIFEST} declares workspaces ${JSON.stringify(pkg.workspaces ?? null)}; every app is a monorepo whose npm workspaces are exactly ${JSON.stringify(WORKSPACES)} (each fe app and package has its own package.json; be has none).`, { workspaces: pkg.workspaces ?? null }));
+    const wanted = workspacesFor(files);
+    if (!sameList(pkg.workspaces, wanted))
+        findings.push(found(MONO_WORKSPACES, MANIFEST, `${MANIFEST} declares workspaces ${JSON.stringify(pkg.workspaces ?? null)}; every app is a monorepo whose npm workspaces are exactly ${JSON.stringify(wanted)} (each fe app and package has its own package.json; be has none; ${ROOT_PACKAGES_WORKSPACE} is listed when the app tracks a root package).`, { workspaces: pkg.workspaces ?? null }));
     if (!PACKAGE_MANAGER_FORM.test(String(pkg.packageManager ?? '')))
         findings.push(found(MONO_WORKSPACES, MANIFEST, `${MANIFEST} declares packageManager ${JSON.stringify(pkg.packageManager ?? null)}; turbo needs \`npm@<exact version>\` there.`, { packageManager: pkg.packageManager ?? null }));
     if (typeof pkg.devDependencies?.turbo !== 'string')
@@ -234,7 +239,7 @@ export function monorepoFindings({ repoRoot, files, repo }) {
     const workspaces = workspacesOf(files);
     const beApps = repo.sides.be.apps;
     return [
-        ...rootFindings(repoRoot),
+        ...rootFindings(repoRoot, files),
         ...workspaceManifestFindings(repoRoot, repo.project, workspaces),
         ...nestFindings(repoRoot, files, beApps),
         ...workspaceDepFindings(repoRoot, files, workspaces),

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

@@ -8,6 +8,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { FORBIDDEN_FILES, secretHitsInFile } from '../../lib/secret-patterns.mjs';
+import { SECRETS_CACHE_FILE, secretRecordFaults } from '../../lib/secret-records.mjs';
 import { isSopsEnvelope } from '../../lib/sops-envelope.mjs';
 import { found, readText } from './read.mjs';
 const PLAINTEXT_SECRET = 'HFS_PLAINTEXT_SECRET';
@@ -28,6 +29,14 @@ export function untrackedSecretFindings({ repoRoot, files, repo }) {
     }
     return [found(PLAINTEXT_SECRET, 'secrets.env', 'secrets.env is an untracked plaintext secret at the lite app root; seal it with starci app secret set --env <env> into .starcistacks/<env>/secrets/<slug>.enc and remove the plaintext file; read materialized values by *_FILE', { level: 'warning', pattern: 'untracked-secrets-env' })];
 }
+/** The findings of a file of the committed secrets cache: it is judged by what it holds (codes, paths, positions and digests, secret-records.mjs), never by the `secrets/` folder it sits in. */
+function cacheRecordFindings(file, text) {
+    const faults = secretRecordFaults(text);
+    if (faults.length === 0)
+        return [];
+    const more = faults.length > 1 ? ` (and ${faults.length - 1} more)` : '';
+    return [found(PLAINTEXT_SECRET, file, `${file}: ${faults[0]}${more}; the secrets cache holds codes, paths, positions and digests only, so a file that holds more may carry secret material; regenerate it with starci app check --gate secrets, or migrate it with starci app codemod secrets-cache --execute`, { pattern: 'secrets-cache-record' })];
+}
 /**
  * The findings of R06 for one tracked file that no forbidden slot claims: a secret by being (an env file, a key file), an `.enc` that is
  * no sops envelope, or a line that matches a secret pattern. `text` is the file's text, or null when it cannot be read (binary, too
@@ -39,6 +48,8 @@ export function secretFileFindings({ file, text, manifestText }) {
         return [found(PLAINTEXT_SECRET, file, `${file} is a plaintext secret by being (${being.name}); a secret is committed only as a sops envelope at .starcistacks/<env>/secrets/<slug>.enc`, { pattern: being.name })];
     if (text === null || text === undefined || NOT_SCANNED.test(file))
         return [];
+    if (SECRETS_CACHE_FILE.test(file))
+        return cacheRecordFindings(file, text);
     if (/\.enc(?:\.yaml)?$/.test(file))
         return isSopsEnvelope(text) ? [] : [found(PLAINTEXT_SECRET, file, `${file} is named like a sealed secret but is not a sops envelope; encrypt the value with sops and commit only the envelope`, { pattern: 'sops-not-envelope' })];
     const findings = [];

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-errors.d.mts

@@ -1,4 +1,7 @@
+/** A refusal with a message safe to print; `code` names it when a caller or a spec keys on it. */
 export declare class SecretError extends Error {
+    code: string | undefined;
+    constructor(message: string, code?: string);
 }
 export declare const publicStorage: <T>(action: () => T) => T;
 export declare function secretErrorMessage(caught: unknown): string;

package/runtime/scripts/hfs/secret-errors.mjs

@@ -1,11 +1,19 @@
 // secret-errors.mjs - sanitized public errors shared by app secret operations.
+/** A refusal with a message safe to print; `code` names it when a caller or a spec keys on it. */
 export class SecretError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
 }
 export const publicStorage = (action) => {
     try {
         return action();
     }
     catch (caught) {
+        if (caught instanceof SecretError)
+            throw caught;
         // reason: a thrown value is untyped; storage failures are Node errors carrying an optional code.
         const error = caught;
         throw new SecretError(error.code ? `private storage failed (${error.code})` : error.message);

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

@@ -72,6 +72,12 @@ export declare function decryptionIdentity(repoRoot: string, env: NodeJS.Process
 export declare function ageIdentityEnv(repoRoot: string, env: NodeJS.ProcessEnv, tools?: SecretToolOverrides): NodeJS.ProcessEnv;
 /** Select the first matching public age rule, including for SOPS's isolated CI identity path. */
 export declare function configuredRecipients(repoRoot: string, file: string): string[];
+/**
+ * Whether sops itself finds a creation rule for `file`: the first rule whose path_regex matches the path as written (sops reads the file's own
+ * name, so a `.enc.yaml` member is not matched by a rule written for the legacy `.enc` spelling, which configuredRecipients tolerates when it
+ * only reads recipients). A rule with no path_regex matches everything.
+ */
+export declare function sopsFindsRule(repoRoot: string, file: string): boolean;
 /** Resolve required tools without exposing subprocess output (which can contain private data). */
 export declare function secretTools(env: NodeJS.ProcessEnv, tools?: SecretToolOverrides): SecretTools;
 /**

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

@@ -154,6 +154,29 @@ export function configuredRecipients(repoRoot, file) {
         throw new Error(".sops.yaml must supply public age recipients for this secret; run starci app secret init");
     return recipients;
 }
+/**
+ * Whether sops itself finds a creation rule for `file`: the first rule whose path_regex matches the path as written (sops reads the file's own
+ * name, so a `.enc.yaml` member is not matched by a rule written for the legacy `.enc` spelling, which configuredRecipients tolerates when it
+ * only reads recipients). A rule with no path_regex matches everything.
+ */
+export function sopsFindsRule(repoRoot, file) {
+    let config; // reason: parsed YAML boundary, read from disk
+    try {
+        config = parseYaml(fs.readFileSync(path.join(repoRoot, ".sops.yaml"), "utf8"));
+    }
+    catch {
+        return false;
+    }
+    const relative = path.relative(repoRoot, file).split(path.sep).join("/");
+    return (config?.creation_rules ?? []).some((entry) => {
+        try {
+            return !entry.path_regex || new RegExp(entry.path_regex).test(relative) || new RegExp(entry.path_regex).test(relative.replaceAll("/", "\\"));
+        }
+        catch {
+            return false;
+        }
+    });
+}
 /** Resolve required tools without exposing subprocess output (which can contain private data). */
 export function secretTools(env, tools = {}) {
     const sops = (tools.resolveSops ?? resolveSops)(env);

package/runtime/scripts/hfs/secret-sops.mjs

@@ -10,7 +10,7 @@ import { updateKeys as sopsUpdateKeys } from "../api/sops/update-keys.mjs";
 import { isLegacyName } from "../lib/sealed-member.mjs";
 import { invocationDir } from "../lib/roots.mjs";
 import { envelopeOf } from "./secret-document.mjs";
-import { configuredRecipients, decryptionIdentity, secretTools, } from "./secret-init.mjs";
+import { configuredRecipients, sopsFindsRule, decryptionIdentity, secretTools, } from "./secret-init.mjs";
 import { outsideRepository } from "./secret-files.mjs";
 import { SecretError, publicStorage } from "./secret-errors.mjs";
 const sopsInvocation = Object.freeze({ runProgram, resolveRealTool });
@@ -83,9 +83,17 @@ function identityMissing(repoRoot, identity, file) {
  * the existing member is sealed to, so no rewrite (set, migrate, split, an edit) drops a recipient such as the deploy server's.
  * `ruled` says whether a rule of the app's .sops.yaml matches the file. Refused, as the rule refuses, when none names one.
  */
+/** The refusal for a member no creation rule of `.sops.yaml` reaches, naming the path and the way to the per-environment rules. */
+function unruledMessage(repoRoot, file) {
+    const relative = path.relative(repoRoot, file).split(path.sep).join("/");
+    const environment = /^\.starcistacks\/([^/]+)\//.exec(relative)?.[1] ?? "<env>";
+    return `SECRET_SOPS_RULE_MISSING: no creation rule of .sops.yaml matches ${relative} (a rule written for the legacy .enc spelling does not match .enc.yaml), so sops cannot seal it; run starci app secret init --env ${environment}, which writes the per-environment rules, or starci app codemod sops-rules --execute to migrate the file`;
+}
 function sealRecipients(repoRoot, file, named) {
     try {
         const rule = configuredRecipients(repoRoot, file);
+        if (!sopsFindsRule(repoRoot, file))
+            throw new SecretError(unruledMessage(repoRoot, file), "SECRET_SOPS_RULE_MISSING");
         return { recipients: named.length ? named : rule, ruled: true };
     }
     catch (error) {

package/runtime/scripts/hfs/secret-standard.d.mts

@@ -59,6 +59,25 @@ export declare function sshTransportMembers(spec: EnvironmentSpec | undefined):
  * RECIPIENT_DRIFT, UNDECLARED_KEY (only where application-stacks.yaml declares the environment), UNTRACKED. Names only.
  */
 export declare function auditSecrets(repoRoot: string, environment?: string | null): AuditFinding[];
+/** What `secret set` did with a member that is a service credential (tooling, never an app runtime secret): the keys it bound, or the remedy to apply by hand. */
+export interface ToolingOutcome {
+    bound: string[];
+    remedy: string;
+}
+/** One sealed tooling member `bindToolingMembers` judged: what it bound, the remedy when it could not, and the runtime entries an earlier `secret set` declared for it. */
+export interface ToolingMember {
+    environment: string;
+    member: string;
+    service: string;
+    outcome: ToolingOutcome;
+    runtimeEntries: string[];
+}
+/**
+ * The tooling members of the app (a sealed `.starcistacks/<env>/secrets/<member>.enc.yaml` that a service of application-stacks.yaml owns): each is bound
+ * to its service when `write` and the binding is missing in the shape the template renders. The runtime `secrets:` entries an earlier `secret set` declared for
+ * the member are named, not removed: the owner deletes them (CI custody refuses the token while one stands).
+ */
+export declare function bindToolingMembers(repoRoot: string, write: boolean): ToolingMember[];
 /**
  * Declares each of `keys` of `member` in environment `environment`'s `secrets:` of application-stacks.yaml, one entry per key
  * (`name: <kebab of the key>, member, key, where: secrets/<member>`), so the key is materialized as its own `<KEY>_FILE`. A key
@@ -68,6 +87,7 @@ export declare function auditSecrets(repoRoot: string, environment?: string | nu
 export declare function declareKeys(repoRoot: string, environment: string, member: string, keys: string[]): {
     declared: string[];
     byHand: string[];
+    tooling?: ToolingOutcome;
 };
 /**
  * Records `recipient` as `environments.<environment>.deploy.remote.serverRecipient` of application-stacks.yaml: the public age