@starci/hfs 4.12.0 → 4.13.0

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

@@ -113,6 +113,12 @@ 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>;

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

@@ -17,7 +17,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', 'ingress', 'registry'],
     remote: ['host', 'releasesBase', 'sealed', 'serverRecipient'],
     image: ['app', 'buildArgs'],
     buildArgs: ['values', 'sealed'],
@@ -38,6 +38,34 @@ const FIELDS = {
     registry: ['host', 'visibility'],
 };
 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)) {
@@ -414,6 +442,9 @@ 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,

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 {};