@starci/hfs 4.12.2 → 4.13.2

package/runtime/scripts/hfs/rules/release-provenance.mjs

@@ -1,4 +1,5 @@
-// R271: a product release keeps its v<semver> tag, root package version, image tags and database deployment ref together.
+// R271: a product release keeps its v<semver> tag, root package version, image tags and database deployment ref together. The pushed images are named by the
+// commit (sha-<sha>); the release name v<version> is a retag of that digest under a release guard. A migration runs in the stack deploy after the release tag.
 // Ordinary untagged development trees have no release version to compare. Workflow checks still run there in both editions.
 // YAML is parsed, so comments and unrelated jobs cannot supply a guard. Shell guards are deliberately a small, explicit form;
 // opaque helper scripts and computed image metadata cannot prove provenance in this static check.
@@ -171,10 +172,12 @@ function dbJobConstrained(job, guarded) {
         constrained = false;
     return constrained;
 }
+// The database deploy workflow is retired in a lite app: its migrations are the migrate phase of the stack deploy (starci app stack deploy, tag-gated by
+// stack-deploy.yml). A full app that keeps its own db-deploy.yml, and a lite app that has not synced yet, are still judged here.
 function dbFindings(file, workflow) {
     const jobs = Object.entries(workflow.jobs ?? {});
     if (!jobs.length)
-        return [found(HFS_DB_DEPLOY_UNGUARDED, file, `${file} has no verifiable database deploy job; require a release tag before migration`)];
+        return [found(HFS_DB_DEPLOY_UNGUARDED, file, `${file} has no verifiable database deploy job; require a release tag before migration (a lite app's migrations are the migrate phase of the stack deploy: run starci app sync --execute to retire this file)`)];
     const findings = [];
     for (const [name, job] of jobs) {
         if (!job || typeof job !== 'object')
@@ -203,17 +206,42 @@ function imageTagIsRelease(value, version) {
         return SEMVER.test(String(version)) && ref.endsWith(`:v${version}`);
     });
 }
+/** A commit tag: `<repo>:sha-${{ github.sha }}`, immutable and per commit, so any ref may push it. */
+const COMMIT_TAG = /^.+:sha-\$\{\{\s*github\.sha\s*\}\}$/;
+function imageTagsAreCommit(value) {
+    if (typeof value !== 'string')
+        return false;
+    const tags = value.split(/[\n,]+/).map((tag) => tag.trim()).filter(Boolean);
+    return tags.length > 0 && tags.every((tag) => COMMIT_TAG.test(tag));
+}
+/** The release guard of a reusable images workflow: a step under `if: ${{ inputs.release }}` whose script rejects a ref that is not refs/tags/v*. */
+function inputReleaseGuard(step) {
+    if (typeof step.run !== 'string' || step['continue-on-error'] || !/^\$\{\{\s*inputs\.release\s*\}\}$/.test(String(step.if ?? '').trim()))
+        return false;
+    const first = step.run.trim().split(/\r?\n/)[0].trim();
+    return /^\[\[\s*["']?\$(?:GITHUB_REF|\{GITHUB_REF\})["']?\s*==\s*refs\/tags\/v\*\s*\]\]\s*\|\|\s*exit\s+[1-9]\d*\s*;?$/.test(first);
+}
+/** The release name v<version> is a retag of the commit digest (`imagetools create --tag <repo>:$GITHUB_REF_NAME <repo>:sha-...`): only after the guard, only on a release run. */
+function retagIsGuarded(job, step) {
+    const steps = job.steps ?? [];
+    const guard = steps.findIndex(inputReleaseGuard);
+    return guard >= 0 && guard < steps.indexOf(step) && /^\$\{\{\s*inputs\.release\s*&&/.test(String(step.if ?? '').trim());
+}
 function imageFindings(file, workflow, version) {
     const findings = [];
     let builds = 0;
     for (const [name, job] of Object.entries(workflow.jobs ?? {})) {
         for (const step of job?.steps ?? []) {
+            if (typeof step.run === 'string' && /\bimagetools\s+create\b/.test(step.run) && !retagIsGuarded(job, step)) {
+                findings.push(found(HFS_RELEASE_TAG_MISMATCH, file, `${file} job ${name} retags an image outside a release guard; put it after a step \`if: \${{ inputs.release }}\` that rejects a ref other than refs/tags/v*, and under \`if: \${{ inputs.release && ... }}\``, { job: name }));
+            }
             if (!(step.uses ?? '').startsWith('docker/build-push-action@'))
                 continue;
             builds += 1;
             const guarded = tagOnlyTrigger(workflow) || refProof(job.if) === RELEASE_REF || refProof(step.if) === RELEASE_REF;
-            if (!guarded || !checkoutPreservesRef(job) || !imageTagIsRelease(step.with?.tags, version))
-                findings.push(found(HFS_RELEASE_TAG_MISMATCH, file, `${file} job ${name} must build the checked-out release ref and tag every image with v<package.json version> or github.ref_name under a release-tag guard`, { job: name }));
+            // An immutable commit tag (sha-<sha>) is pushed by any ref; a release name must come from the checked-out release ref under a guard.
+            if (!checkoutPreservesRef(job) || !(imageTagsAreCommit(step.with?.tags) || (guarded && imageTagIsRelease(step.with?.tags, version))))
+                findings.push(found(HFS_RELEASE_TAG_MISMATCH, file, `${file} job ${name} must build the checked-out ref and tag every image with sha-\${{ github.sha }} (the release name v<package.json version> is a guarded retag of that digest), or tag with v<version> or github.ref_name under a release-tag guard`, { job: name }));
         }
     }
     if (!builds)

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

@@ -20,7 +20,8 @@ const allowedExpressions = (allows) => allows.flatMap((entry) => braceVariants(e
 const shapeFinding = (file, message, extra) => found(STACKS_SHAPE, file, message, extra);
 function treeFindings(files, allowed, prefix) {
     const findings = [];
-    for (const file of files.filter((f) => f.startsWith(prefix))) {
+    // `cache` is reserved: .starcistacks/cache/ is the committed check cache (slot app.starcistacks.cache), written by the CLI, not an environment.
+    for (const file of files.filter((f) => f.startsWith(prefix) && !f.startsWith(`${prefix}cache/`))) {
         const rel = file.slice(prefix.length);
         if (/\.enc(?:\.yaml)?$/.test(rel) && !INSIDE_SECRETS.test(rel))
             findings.push(shapeFinding(file, `${file} is a sealed secret outside <env>/secrets/<slug>.enc.yaml; move it to .starcistacks/<env>/secrets/`));
@@ -34,6 +35,9 @@ function declarationFindings(files, prefix, declaration) {
     if (!files.includes(declared))
         return [];
     const findings = [];
+    const environments = declaration.doc?.environments;
+    if (environments !== null && typeof environments === 'object' && Object.hasOwn(environments, 'cache'))
+        findings.push(shapeFinding(declared, `${declared} declares an environment named cache; the name is reserved for the committed check cache (.starcistacks/cache/)`));
     if (declaration.error)
         return [shapeFinding(declared, `${declared} cannot be read: ${declaration.error}`)];
     const services = declaration.doc?.services;

package/runtime/scripts/hfs/rules/supply-chain.mjs

@@ -5,7 +5,10 @@ const DEPENDABOT = '.github/dependabot.yml';
 const CI = '.github/workflows/ci.yml';
 const IMAGES = '.github/workflows/images.yml';
 const ECOSYSTEMS = ['npm', 'github-actions', 'docker'];
-const enabled = (entry) => entry && (entry.if === undefined || entry.if === true || entry.if === 'true') && !entry['continue-on-error'];
+// A job the plan or the caller decides is no disabled job: a reusable workflow runs a job on `if: ${{ inputs.release }}` whenever its caller asks, and the CI jobs
+// run on `if: ${{ needs.plan.outputs.checks == 'true' }}` on every run that checks (the plan leaves them out only where a green run of the same commit stands in).
+const DECIDED_CONDITION = /^\$\{\{\s*(?:inputs\.[A-Za-z_][\w-]*|needs\.plan\.outputs\.[A-Za-z_]\w*\s*==\s*'true')\s*\}\}$/;
+const enabled = (entry) => entry && (entry.if === undefined || entry.if === true || entry.if === 'true' || (typeof entry.if === 'string' && DECIDED_CONDITION.test(entry.if.trim()))) && !entry['continue-on-error'];
 function shellSeparator(line, index, quote) {
     if (quote)
         return null;

package/runtime/scripts/hfs/rules/unused-symbol-translators.mjs

@@ -126,21 +126,110 @@ function bindTranslator(state, name, initializer, factories) {
             bindTranslator(state, element.name, elements[index], factories); });
     }
 }
+/**
+ * The key a translator helper's member is known by in its declared type: the app's own type alias the member is typed with
+ * (`readonly t: OfficeText`), else the member itself. An alias with type arguments or one declared outside the app's sources is no key.
+ */
+function declaredTranslatorKey(state, type, member) {
+    const alias = type?.aliasSymbol;
+    if (alias) {
+        const declarations = alias.declarations ?? [];
+        const own = declarations.length > 0 && declarations.every((declaration) => state.sourceNames?.has(declaration.getSourceFile().fileName));
+        return own && !type.aliasTypeArguments?.length ? alias : null;
+    }
+    return member ?? null;
+}
+/**
+ * The declared object type an object literal is written for: its contextual type, or, when the literal is what `useMemo(() => literal)` makes
+ * and React's own types are not part of the program, the type argument of that useMemo or the type the call itself is written for.
+ */
+function literalType(state, literal) {
+    const { ts, checker } = state;
+    const known = (type) => type && !(type.flags & ts.TypeFlags.Any) && type.getProperties().length > 0 ? type : null;
+    const contextual = known(checker.getContextualType(literal));
+    if (contextual)
+        return contextual;
+    let body = literal;
+    while (ts.isParenthesizedExpression(body.parent))
+        body = body.parent;
+    let fn = body.parent;
+    if (fn && ts.isReturnStatement(fn)) {
+        while (fn && !ts.isFunctionLike(fn))
+            fn = fn.parent;
+    }
+    else if (!fn || !ts.isArrowFunction(fn) || fn.body !== body)
+        return null;
+    if (!fn || !ts.isArrowFunction(fn) && !ts.isFunctionExpression(fn))
+        return null;
+    const call = fn.parent;
+    if (!call || !ts.isCallExpression(call) || call.arguments[0] !== fn || leafName(ts, call.expression) !== 'useMemo')
+        return null;
+    const [argument] = call.typeArguments ?? [];
+    return known(argument ? checker.getTypeFromTypeNode(argument) : checker.getContextualType(call));
+}
+/**
+ * A helper that exposes a bound translator as a member of a declared object type (`useMemo<OfficeWords>(() => ({ t: (key, values) => t(key, values) }))`)
+ * binds that member's declared type: every value of that type, wherever the helper is handed on, reads in the namespaces bound to it.
+ */
+function bindTypedMember(state, property, factories) {
+    const { ts, checker } = state;
+    const literal = property.parent;
+    if (!ts.isObjectLiteralExpression(literal))
+        return;
+    const name = nameText(ts, property.name, { numbers: true });
+    if (name === null)
+        return;
+    const initializer = ts.isShorthandPropertyAssignment(property) ? property.name : property.initializer;
+    const value = unwrap(ts, initializer);
+    const namespaces = value && ts.isIdentifier(value)
+        ? state.translators.get(symbolAt(state, value)) ?? wrapperNamespaces(state, value)
+        : translatorNamespace(state, initializer, factories) ?? wrapperNamespaces(state, initializer);
+    if (!namespaces?.length)
+        return;
+    const member = literalType(state, literal)?.getProperty(name);
+    if (!member)
+        return;
+    const key = declaredTranslatorKey(state, checker.getTypeOfSymbolAtLocation(member, literal), member);
+    if (!key)
+        return;
+    const bound = state.typedTranslators.get(key) ?? new Set();
+    for (const namespace of namespaces)
+        bound.add(namespace);
+    state.typedTranslators.set(key, bound);
+}
 /** Wrappers depend on translators bound in other modules, so bind until nothing new appears. */
 export function translationBindings(state, sources) {
+    const { ts } = state;
     const factories = new Map([...sources.values()].map(source => [source, translationFactories(state, source)]));
-    for (let pass = 0, size = -1; pass < 4 && size !== state.translators.size; pass++) {
-        size = state.translators.size;
+    state.typedTranslators ??= new Map();
+    state.sourceNames ??= new Set([...sources.values()].map((source) => source.fileName));
+    const typedSize = () => [...state.typedTranslators.values()].reduce((sum, bound) => sum + bound.size, 0);
+    for (let pass = 0, size = -1; pass < 4 && size !== state.translators.size + typedSize(); pass++) {
+        size = state.translators.size + typedSize();
         for (const source of sources.values()) {
             const visit = (node) => {
-                if (state.ts.isVariableDeclaration(node) && node.initializer)
+                if (ts.isVariableDeclaration(node) && node.initializer)
                     bindTranslator(state, node.name, node.initializer, factories.get(source));
-                state.ts.forEachChild(node, visit);
+                if (ts.isPropertyAssignment(node) || ts.isShorthandPropertyAssignment(node))
+                    bindTypedMember(state, node, factories.get(source));
+                ts.forEachChild(node, visit);
             };
             visit(source);
         }
     }
 }
+/** The namespaces bound to the declared type of a receiver (its own type alias, or the member it reads), if a translator helper bound it. */
+function typedNamespaces(state, receiver) {
+    const { ts, checker } = state;
+    if (!state.typedTranslators?.size)
+        return [];
+    const node = unwrap(ts, receiver);
+    if (!node)
+        return [];
+    const member = ts.isPropertyAccessExpression(node) ? symbolAt(state, node.name) : null;
+    const keys = [declaredTranslatorKey(state, checker.getTypeAtLocation(node), null), member];
+    return [...new Set(keys.flatMap(key => key ? [...state.typedTranslators.get(key) ?? []] : []))];
+}
 /** Namespaces of the translators a receiver can be: declared here, or handed in through arguments and props. */
 function receiverNamespaces(state, receiver) {
     const { ts, checker } = state;
@@ -201,11 +290,13 @@ export function catalogNamespace(state, callee) {
     const resolved = receiverNamespaces(state, receiver);
     if (resolved.length)
         return resolved;
+    // A value of a type a translator helper bound reads in that helper's namespaces, on top of what the fallbacks below allow.
+    const typed = typedNamespaces(state, receiver);
     const binding = receiverBinding(state, receiver);
     // Observed unresolved producers cannot use the generic namespace fallback.
     if (binding.handedIn && (TRANSLATOR_NAME.test(leafName(ts, receiver)) || translatorShaped(state, receiver)))
-        return binding.observed ? [] : [null];
+        return binding.observed ? typed : [...typed, null];
     if (ts.isIdentifier(callee) && TRANSLATOR_NAME.test(callee.text))
-        return binding.observed ? [] : [''];
-    return [];
+        return binding.observed ? typed : [...typed, ''];
+    return typed;
 }

package/runtime/scripts/hfs/rules/unused-symbol.d.mts

@@ -1,11 +1,18 @@
 import type { Parsed, Repo } from './rule-types.mjs';
 export declare const HFS_UNUSED_SYMBOL = "HFS_UNUSED_SYMBOL";
 /** The same rule applies to lite and full. Analyze all tracked consumers before filtering findings to a fast-check scope. */
-export declare function unusedSymbolFindings({ repoRoot, files, repo, isRoot, inScope, ts: supplied }: {
+type UnusedSymbolInput = {
     repoRoot: string;
     files: string[];
     repo?: Repo;
     isRoot?: boolean;
     inScope?: (file: string) => boolean;
     ts: Parsed;
-}): any[];
+};
+/** A seam for the app check cache: the whole-program analysis of a side is a scoped step keyed on the side, so the cache runs it only when the side changed. */
+export interface UnusedSymbolMemo {
+    run(repoRoot: string, compute: () => Parsed[]): Parsed[];
+}
+export declare function withUnusedSymbolMemo<T>(seam: UnusedSymbolMemo, work: () => T): T;
+export declare function unusedSymbolFindings(input: UnusedSymbolInput): any[];
+export {};

package/runtime/scripts/hfs/rules/unused-symbol.mjs

@@ -339,8 +339,21 @@ function catalogRead(state, candidate, liveCodes) {
         });
     });
 }
-/** The same rule applies to lite and full. Analyze all tracked consumers before filtering findings to a fast-check scope. */
-export function unusedSymbolFindings({ repoRoot, files, repo = {}, isRoot = false, inScope = () => true, ts: supplied }) {
+let memo = null;
+export function withUnusedSymbolMemo(seam, work) {
+    const previous = memo;
+    memo = seam;
+    try {
+        return work();
+    }
+    finally {
+        memo = previous;
+    }
+}
+export function unusedSymbolFindings(input) {
+    return memo === null ? computeUnusedSymbols(input) : memo.run(input.repoRoot, () => computeUnusedSymbols(input));
+}
+function computeUnusedSymbols({ repoRoot, files, repo = {}, isRoot = false, inScope = () => true, ts: supplied }) {
     const edition = repo.edition ?? 'full';
     if (isRoot || repo.kind === 'runtime' || !['lite', 'full'].includes(edition))
         return [];

package/runtime/scripts/hfs/runtime-rules/git-triggers.mjs

@@ -1,4 +1,5 @@
-// CI_TRIGGERS_RELEASE_ONLY: runtime workflows and app ci.yml may judge main; release candidates, v* tags and manual dispatch retain their scope.
+// CI_TRIGGERS_RELEASE_ONLY: runtime workflows and app ci.yml may judge main; release candidates, v* tags and manual dispatch retain their scope. ci.yml also judges pull requests
+// to main (pull_request only: no secret reaches it; pull_request_target, workflow_run and schedules stay refused); a reusable workflow (workflow_call) has no trigger of its own.
 import { parseWorkflow, workflowFindings } from './workflow-source.mjs';
 import { workflowEventOptions } from '../../lib/workflow-events.mjs';
 export const CODE = 'CI_TRIGGERS_RELEASE_ONLY';
@@ -36,11 +37,26 @@ function pushFindings({ ownBranch, config, refuse, release }) {
         found.push(refuse(`\`push.${other}\` is not allowed beside the trigger filters`));
     return found;
 }
-function eventFindings({ event, config, ownBranch, refuse, release }) {
-    if (event === 'workflow_dispatch')
+/** A pull request to main, in ci.yml only: the checks of a change, with no filter beyond the base branch. */
+function pullRequestFindings({ file, config, refuse }) {
+    if (!RELEASE_WORKFLOW.test(file))
+        return [refuse('`pull_request` may start only ci.yml: no other workflow runs the code of a pull request')];
+    const filters = config && typeof config === 'object' && !Array.isArray(config) ? config : {};
+    const found = [];
+    const branches = filters.branches;
+    if (!Array.isArray(branches) || branches.length !== 1 || String(branches[0]) !== RUNTIME_BRANCH)
+        found.push(refuse(`\`pull_request.branches\` must be exactly ['${RUNTIME_BRANCH}']`));
+    for (const other of Object.keys(filters).filter((key) => key !== 'branches'))
+        found.push(refuse(`\`pull_request.${other}\` is not allowed beside the base branch`));
+    return found;
+}
+function eventFindings({ file, event, config, ownBranch, refuse, release }) {
+    if (event === 'workflow_dispatch' || event === 'workflow_call')
         return [];
+    if (event === 'pull_request')
+        return pullRequestFindings({ file, config, refuse });
     if (event !== 'push')
-        return [refuse(`the trigger \`${event}\` is not allowed: only a push of release tags [${RELEASE_TAGS}], of '${CANDIDATE_BRANCHES}' (and, in runtime workflows or app ci.yml, of branch ${RUNTIME_BRANCH}) and workflow_dispatch may start CI`)];
+        return [refuse(`the trigger \`${event}\` is not allowed: only a push of release tags [${RELEASE_TAGS}], of '${CANDIDATE_BRANCHES}' (and, in runtime workflows or app ci.yml, of branch ${RUNTIME_BRANCH}), a pull request to ${RUNTIME_BRANCH} in ci.yml, workflow_call and workflow_dispatch may start CI`)];
     return pushFindings({ ownBranch, config, refuse, release });
 }
 /** The CI_TRIGGERS_RELEASE_ONLY findings of one workflow text; a text that is not YAML yields none (the other checks name it). Runtime workflows and app ci.yml may also push on main. */
@@ -56,7 +72,7 @@ function workflowTriggerFindings({ path: file, text }) {
     const events = workflowEventOptions(on, String);
     const release = !file.startsWith('.github/workflows/') && RELEASE_WORKFLOW.test(file);
     const missingPush = release && !Object.hasOwn(events, 'push') ? [refuse(`the app release workflow must run on a push of '${CANDIDATE_BRANCHES}' and of tags [${RELEASE_TAGS}]`)] : [];
-    return [...missingPush, ...Object.entries(events).flatMap(([event, config]) => eventFindings({ event, config, ownBranch, refuse, release }))];
+    return [...missingPush, ...Object.entries(events).flatMap(([event, config]) => eventFindings({ file, event, config, ownBranch, refuse, release }))];
 }
 /** CI_TRIGGERS_RELEASE_ONLY over every tracked workflow (ctx of scripts/hfs/runtime-check.mjs). */
 export const gitTriggerFindings = (ctx) => workflowFindings(ctx, workflowTriggerFindings);

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

@@ -99,6 +99,16 @@ export interface BackupConfig {
         volume: string;
     }>;
 }
+/** The outcomes of a deploy attempt a notification can be sent for. */
+export declare const NOTIFY_OUTCOMES: readonly ["accepted", "rolled-back", "rollback-failed", "failed", "refused"];
+/** `deploy.notify`: the sealed member and key that hold the webhook URL (https), and the outcomes that are announced. */
+export interface NotifyConfig {
+    webhook: {
+        member: string;
+        key: string;
+    };
+    on: string[];
+}
 export interface RegistryConfig {
     host: string;
     visibility: string;
@@ -113,11 +123,19 @@ export interface DeployConfig {
     environment: Record<string, ServiceEnvironment>;
     configs: ConfigEntry[];
     passEnv: string[];
+    /** deploy.auto: a green release tag deploys here by itself. */
+    auto: boolean;
+    /** deploy.approval: none, or reviewers set on the GitHub Environment. */
+    approval: 'none' | 'reviewers';
+    /** deploy.platforms: the platforms the images are built for (default linux/amd64). */
+    platforms: string[];
     verify: VerifyConfig;
     jobs: JobsConfig | null;
     tasks: Record<string, TaskConfig>;
     postDeploy: string[];
     backup: BackupConfig | null;
+    /** deploy.notify: one webhook message per deploy outcome; null (off) unless declared. */
+    notify: NotifyConfig | null;
     ingress: IngressConfig | null;
     registry: RegistryConfig;
 }

package/runtime/scripts/hfs/stack-deploy-config.mjs

@@ -5,6 +5,8 @@ import { isPlainObject as plain } from '../../engine/plain-object.mjs';
 import { closedFields, collector, patternField, treeFile } from './stack-config-kit.mjs';
 import { list } from '../lib/list.mjs';
 import { normalizeIngress } from './stack-ingress-config.mjs';
+/** The outcomes of a deploy attempt a notification can be sent for. */
+export const NOTIFY_OUTCOMES = ['accepted', 'rolled-back', 'rollback-failed', 'failed', 'refused'];
 export const DEPLOY_CONFIG_CODE = 'STACKS_DEPLOY_CONFIG_INVALID';
 export const NAME = /^[a-z][a-z0-9-]*$/u;
 export const KEY = /^[A-Z][A-Z0-9_]*$/u;
@@ -17,7 +19,7 @@ const PINNED_HELPER_IMAGE = /^[a-z0-9./_-]+(?::[A-Za-z0-9._-]+)?@sha256:(?!0{64}
 const ARGUMENT = /^[A-Za-z0-9_@%+=:,./-]+$/u;
 const UPPER_ENV = KEY;
 const FIELDS = {
-    deploy: ['stack', 'remote', 'images', 'volumes', 'secrets', 'environment', 'configs', 'passEnv', 'postDeploy', 'verify', 'jobs', 'tasks', 'backup', 'ingress', 'registry'],
+    deploy: ['stack', 'remote', 'images', 'volumes', 'secrets', 'environment', 'configs', 'passEnv', 'auto', 'approval', 'platforms', 'postDeploy', 'verify', 'jobs', 'tasks', 'backup', 'notify', 'ingress', 'registry'],
     remote: ['host', 'releasesBase', 'sealed', 'serverRecipient'],
     image: ['app', 'buildArgs'],
     buildArgs: ['values', 'sealed'],
@@ -36,8 +38,38 @@ const FIELDS = {
     backup: ['image', 'keepDays', 'dir', 'volumes'],
     backupVolume: ['name', 'volume'],
     registry: ['host', 'visibility'],
+    notify: ['webhook', 'on'],
+    webhook: ['member', 'key'],
 };
 const text = (value) => typeof value === 'string' && value.length > 0;
+const APPROVALS = ['none', 'reviewers'];
+const PLATFORMS = ['linux/amd64', 'linux/arm64'];
+function flag(c, at, value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'boolean')
+        c.problem(at, 'must be true or false');
+    return value === true;
+}
+function choice(c, at, value, allowed, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'string' || !allowed.includes(value)) {
+        c.problem(at, `must be one of ${allowed.join(', ')}`);
+        return fallback;
+    }
+    return value;
+}
+/** `deploy.platforms`: the platforms the images are built for, default linux/amd64 (the VPS's architecture). */
+function platforms(c, value) {
+    if (value === undefined)
+        return ['linux/amd64'];
+    if (!Array.isArray(value) || value.length === 0 || new Set(value).size !== value.length || value.some((item) => typeof item !== 'string' || !PLATFORMS.includes(item))) {
+        c.problem('deploy.platforms', `must be a list of ${PLATFORMS.join(' and ')}, each once`);
+        return ['linux/amd64'];
+    }
+    return value;
+}
 const nameField = (c, at, value, pattern = NAME) => patternField(c, at, value, pattern);
 function stringList(c, at, value, itemPattern, { nonEmpty = false } = {}) {
     if (!Array.isArray(value) || (nonEmpty && value.length === 0)) {
@@ -381,6 +413,22 @@ function backup(c, block) {
         c.problem('deploy.backup.volumes', 'must list at least one volume');
     return { image: block.image, keepDays: block.keepDays ?? 14, dir: block.dir ?? null, volumes };
 }
+/**
+ * `deploy.notify`: off unless declared. The webhook URL is a sealed value (never in the declaration, the log or the journal); the default announces every
+ * outcome that changed or tried to change the services (accepted, rolled-back, rollback-failed, failed), and `on` narrows or adds `refused`.
+ */
+function notify(c, block, members) {
+    if (block === undefined)
+        return null;
+    if (!closedFields(c, 'deploy.notify', block, FIELDS.notify))
+        return null;
+    if (!closedFields(c, 'deploy.notify.webhook', block.webhook, FIELDS.webhook))
+        return null;
+    memberRef(c, 'deploy.notify.webhook.member', block.webhook.member, members);
+    patternField(c, 'deploy.notify.webhook.key', block.webhook.key, KEY);
+    const on = block.on === undefined ? ['accepted', 'rolled-back', 'rollback-failed', 'failed'] : stringList(c, 'deploy.notify.on', block.on, new RegExp(`^(?:${NOTIFY_OUTCOMES.join('|')})$`, 'u'), { nonEmpty: true });
+    return { webhook: { member: block.webhook.member, key: block.webhook.key }, on };
+}
 function ingress(c, block, probe) {
     if (block === undefined)
         return null;
@@ -414,11 +462,15 @@ export function normalizeDeploy(block, { project, probe }) {
         environment: environmentBlock(c, block.environment, services, probe),
         configs: configs(c, block.configs, probe),
         passEnv: block.passEnv === undefined ? [] : stringList(c, 'deploy.passEnv', block.passEnv, KEY),
+        auto: flag(c, 'deploy.auto', block.auto, false),
+        approval: choice(c, 'deploy.approval', block.approval, APPROVALS, 'none'),
+        platforms: platforms(c, block.platforms),
         verify: verify(c, block.verify, services),
         jobs: jobs(c, block.jobs, services),
         tasks,
         postDeploy: postDeploy(c, block.postDeploy, tasks),
         backup: backup(c, block.backup),
+        notify: notify(c, block.notify, members),
         ingress: ingress(c, block.ingress, probe),
         registry: registry(c, block.registry),
     };

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

@@ -308,6 +308,8 @@ const checkStackEntry = (entry, environmentNames, add, { stacksRoot, lite }) =>
     }
     if (entry.name === 'k8s')
         return;
+    if (entry.name === 'cache')
+        return; // the committed check cache (slot app.starcistacks.cache): reserved, never an environment
     if (lite && entry.name === 'images')
         return; // the managed db image (slot app.db.image, ruling lite-db-image-in-stacks), no environment
     if (lite && liteCustodyDirectory(path.join(stacksRoot, entry.name)))

package/runtime/scripts/hfs/tree-findings.mjs

@@ -1,5 +1,6 @@
 import { readTree, treeFacts, untrackedEntries } from './tree.mjs';
 import { liteStarciworkTreeFindings } from './path-findings.mjs';
+const CHECK_CACHE_DIR = '.starcistacks/cache';
 /** The tree findings of R03: empty directories, ghost siblings, untracked entries outside an ignored slot. */
 export function treeFindings({ repoRoot, resolver, tracked = [], reportedUntracked = new Set() }) {
     const inIgnoredSlot = (rel) => resolver.classifyPath(`${rel}/.probe`).tracking === 'ignored';
@@ -19,5 +20,6 @@ export function treeFindings({ repoRoot, resolver, tracked = [], reportedUntrack
         if (!ignored)
             findings.push({ code: 'HFS_UNTRACKED_ROOT_ENTRY', level: 'error', path: bare, message: `${entry} is neither tracked nor git-ignored, and no ignored slot owns it` });
     }
-    return findings;
+    // The committed check cache is written by the CLI and committed with the change: before that commit its files are untracked, and a run's own output is no finding.
+    return findings.filter((finding) => !(finding.path === CHECK_CACHE_DIR || String(finding.path).startsWith(`${CHECK_CACHE_DIR}/`)));
 }

package/scaffold/add-inbox-lite.mjs

@@ -1,3 +1,4 @@
+import { nextMigrationStamp } from "./migration-stamp.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import { render, TEMPLATES_DIR } from "../sync/index.mjs";
@@ -8,7 +9,6 @@ import { byCodeUnit } from "../report/order.mjs";
 import { withSqlIdentifierError } from "./add-database-lite.mjs";
 const MIGRATION = /^(\d{14})_[a-z][a-z0-9]*(?:-[a-z0-9]+)*\.sql$/;
 const PLACEHOLDER = /@@([A-Za-z][A-Za-z0-9]*)@@/g;
-const timestampOf = (now) => new Date(now()).toISOString().replace(/\D/g, "").slice(0, 14);
 const upperOf = (name) => name.replaceAll("-", "_").toUpperCase();
 const camelOf = (name) => {
     const pascal = pascalOf(name);
@@ -162,10 +162,8 @@ export function addLiteWebhookInbox({ root, repo, noun, provider, values, now =
     const suffix = `${provider}-inbox.sql`;
     if (migrations.some((file) => file.endsWith(`_${suffix}`)))
         throw new ScaffoldError("HFS_ADD_EXISTS", `webhook ${provider} already has an inbox migration`);
-    const stamp = timestampOf(now);
     const latest = migrations.at(-1)?.slice(0, 14);
-    if (latest && stamp <= latest)
-        throw new ScaffoldError("HFS_ADD_MIGRATION_ORDER", `the current UTC timestamp ${stamp} is not later than the latest migration ${latest}; fix the clock or wait for the next second`);
+    const stamp = nextMigrationStamp(now, latest);
     const renderValues = {
         ...values,
         provider,

package/scaffold/add-queue-lite.mjs

@@ -4,6 +4,7 @@
 // its sealed secret. The verb also declares redis in hfs.json sides.be.backing with its bullmq client, and renders the one
 // declared Redis into every docker-swarm environment of the stack: the stateful component, its backup and restore record, the
 // sealed redis-password member and its grants, the AOF service on a named volume and an internal network, and the images lock.
+import { nextMigrationStamp } from './migration-stamp.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseYaml } from '../runtime/engine/yaml.mjs';
@@ -104,10 +105,8 @@ function migrationFiles({ repoRoot, beRoot, patterns, now }) {
         return [];
     const folder = path.join(repoRoot, 'db', 'migrations');
     const migrations = fs.existsSync(folder) ? fs.readdirSync(folder).filter((file) => MIGRATION.test(file)).sort(byCodeUnit) : [];
-    const stamp = new Date(now()).toISOString().replace(/\D/g, '').slice(0, 14);
     const latest = migrations.at(-1)?.slice(0, 14);
-    if (latest && stamp <= latest)
-        throw new ScaffoldError('HFS_ADD_MIGRATION_ORDER', `the current UTC timestamp ${stamp} is not later than the latest migration ${latest}; fix the clock or wait for the next second`);
+    const stamp = nextMigrationStamp(now, latest);
     const text = sections.map(([, , source]) => template(`be/patterns/${source}`)).join('\n');
     return [{ relative: `db/migrations/${stamp}_${sections.map(([name]) => name).join('-')}.sql`, text }];
 }

package/scaffold/add-table.mjs

@@ -1,3 +1,4 @@
+import { nextMigrationStamp } from "./migration-stamp.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import { loadSlotManifest, readRepoDeclaration, } from "../runtime/scripts/hfs/slots.mjs";
@@ -114,7 +115,6 @@ const POSTGRES_RESERVED = new Set([
     "window",
     "with",
 ]);
-const timestampOf = (now) => new Date(now()).toISOString().replace(/\D/g, "").slice(0, 14);
 const snakeOf = (name) => name.replaceAll("-", "_");
 const featureOf = (name) => name.replaceAll("_", "-");
 const sqlIdentifierOf = (name) => POSTGRES_RESERVED.has(name) ? `"${name}"` : name;
@@ -328,10 +328,8 @@ function nextMigration({ root, feature, requestedName, now }) {
         : [];
     if (migrations.some((file) => file.endsWith(`_${feature}.sql`)))
         throw new ScaffoldError("HFS_ADD_EXISTS", `table ${requestedName} already has a migration`);
-    const stamp = timestampOf(now);
     const latest = migrations.at(-1)?.slice(0, 14);
-    if (latest && stamp <= latest)
-        throw new ScaffoldError("HFS_ADD_MIGRATION_ORDER", `the current UTC timestamp ${stamp} is not later than the latest migration ${latest}; fix the clock or wait for the next second`);
+    const stamp = nextMigrationStamp(now, latest);
     return stamp;
 }
 function tableValues({ feature, table }) {

package/scaffold/migration-stamp.d.mts

@@ -0,0 +1,11 @@
+/**
+ * The UTC timestamp (YYYYMMDDHHMMSS) of the next migration: the clock's second, strictly later than the latest migration.
+ * Two migrations written within one second (the scaffold of an app followed at once by `add table`) would collide, so the
+ * stamp then moves to the second after the latest; a latest more than a few seconds ahead of the clock is a clock that is
+ * really behind, and is refused (HFS_ADD_MIGRATION_ORDER).
+ *
+ * @param now - The clock, in milliseconds.
+ * @param latest - The timestamp of the latest migration of the folder, if any.
+ * @returns The 14-digit stamp for the new migration.
+ */
+export declare const nextMigrationStamp: (now: () => number, latest: string | undefined) => string;

package/scaffold/migration-stamp.mjs

@@ -0,0 +1,32 @@
+import { ScaffoldError } from "./service.mjs";
+/** How far ahead of the clock the latest migration may be before the clock counts as behind (a collision, not a wrong clock). */
+const CLOCK_SKEW_SECONDS = 5;
+const STAMP = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})$/u;
+const secondsOf = (stamp) => {
+    const parts = STAMP.exec(stamp);
+    if (!parts)
+        return null;
+    const [, year, month, day, hour, minute, second] = parts.map(Number);
+    return Date.UTC(year ?? 0, (month ?? 1) - 1, day, hour, minute, second) / 1000;
+};
+const stampOfSeconds = (seconds) => new Date(seconds * 1000).toISOString().replace(/\D/gu, "").slice(0, 14);
+/**
+ * The UTC timestamp (YYYYMMDDHHMMSS) of the next migration: the clock's second, strictly later than the latest migration.
+ * Two migrations written within one second (the scaffold of an app followed at once by `add table`) would collide, so the
+ * stamp then moves to the second after the latest; a latest more than a few seconds ahead of the clock is a clock that is
+ * really behind, and is refused (HFS_ADD_MIGRATION_ORDER).
+ *
+ * @param now - The clock, in milliseconds.
+ * @param latest - The timestamp of the latest migration of the folder, if any.
+ * @returns The 14-digit stamp for the new migration.
+ */
+export const nextMigrationStamp = (now, latest) => {
+    const stamp = stampOfSeconds(Math.floor(now() / 1000));
+    if (!latest || stamp > latest)
+        return stamp;
+    const ahead = secondsOf(latest);
+    const current = secondsOf(stamp);
+    if (ahead === null || current === null || ahead - current > CLOCK_SKEW_SECONDS)
+        throw new ScaffoldError("HFS_ADD_MIGRATION_ORDER", `the current UTC timestamp ${stamp} is not later than the latest migration ${latest}; fix the clock or wait for the next second`);
+    return stampOfSeconds(ahead + 1);
+};

package/src/helpers/hfs-arch-fixture.d.mts

@@ -17,8 +17,8 @@ export declare function appDeclaration(side: Side, fields: object, project?: str
     kind: string;
     project: string;
     sides: {
-        fe: object;
         be: object;
+        fe: object;
     };
 };
 /**

package/src/main.d.mts

@@ -39,6 +39,9 @@ interface AppIo {
     stackIo?: Record<string, unknown> | undefined;
     runLinter?: LinterRunner | undefined;
     checkApp?: ((args: Dynamic) => Dynamic) | undefined;
+    /** --quiet: no progress on stderr (the diagnosis stays). */
+    quiet?: boolean | undefined;
+    stderrIsTty?: boolean | undefined;
 }
 /** The options of main: every seam of the app IO, each optional. */
 type MainOptions = {
@@ -54,5 +57,5 @@ export declare function appRootAbove(dir: string): string;
  * the HFS check and `stackIo` Swarm tools; production defaults execute every check. `hostIdentity` ({ label, read }) is the
  * harness CLI's own secret.env SOPS_AGE_KEY, which every verb that opens a sealed member (secret, stack, release, db) reads last for the age identity (decryptionIdentity); `prompt` replaces its masked prompt.
  */
-export declare function main(argv: string[], { cwd: baseCwd, harness, stdout, stderr, presets, prettier, lock, run, stackMain, env, stdin, prompt, hostIdentity, sops, tools, platform, stackIo, runLinter, checkApp, }?: MainOptions): Promise<number>;
+export declare function main(argv: string[], { cwd: baseCwd, harness, stdout, stderr, presets, prettier, lock, run, stackMain, env, stdin, prompt, hostIdentity, sops, tools, platform, stackIo, runLinter, checkApp, stderrIsTty, }?: MainOptions): Promise<number>;
 export {};