@starci/hfs 4.11.21 → 4.12.0

package/release/index.d.mts

@@ -0,0 +1,68 @@
+import { type StackContext } from '../stack/context.mjs';
+/** What a spawned tool answers (ctx.spawn is never a shell). */
+export interface SpawnResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error?: Error | undefined;
+}
+/** The seams every release and database verb runs through: the stack context contextOf builds (stack/context.mjs stackContext). */
+export type VerbContext = StackContext;
+/** The app IO a verb receives from the starci CLI (cwd, writers, environment, secret seams, the stack seams of `stackIo`, the CLI `harness`). */
+export interface VerbIo {
+    cwd?: string | undefined;
+    stdout?: ((text: string) => unknown) | undefined;
+    stderr?: ((text: string) => unknown) | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+    sops?: unknown;
+    hostIdentity?: unknown;
+    stackIo?: Record<string, unknown> | undefined;
+    harness?: {
+        version?: string | undefined;
+        role?: string | undefined;
+        openTicket?: ((ticket: unknown) => unknown) | undefined;
+    } | undefined;
+}
+/** The flags of one verb ({ boolean, value }); the parser refuses every other. */
+export interface FlagSpec {
+    boolean: readonly string[];
+    value: readonly string[];
+}
+/** The parsed flags of a verb: a boolean flag is true, a value flag its string. */
+export type VerbFlags = Record<string, string | boolean | undefined>;
+/** What a verb answers: `ok` maps to the exit code, `lines` print as text and `data` joins the --json answer. */
+export interface VerbResult {
+    ok: boolean;
+    lines?: string[];
+    data?: Record<string, unknown>;
+}
+/** The stack context of one invocation: the IO of the app (cwd, writers, env, sops, hostIdentity) over the injectable seams of `io.stackIo` (spawn, sleep, now, fetch). */
+export declare function contextOf(io?: VerbIo): VerbContext;
+/** The top-level mapping of .starcistacks/application-stacks.yaml; a missing file is an empty declaration, an unreadable one a refusal. */
+export declare function readDeclaration(root: string): Record<string, any>;
+/** The normalised `release:` block (tolerant of absence) with the package version: { root, version, gates, tagPrefix, defaultBranch, requireCi }. */
+export declare function loadReleaseConfig(root: string): {
+    root: string;
+    version: any;
+    gates: import("./gate.mjs").Gate[];
+    tagPrefix: string;
+    defaultBranch: string;
+    requireCi: boolean;
+    services: any;
+};
+/** Parses the flags, runs `run(ctx, flags, positional)` and prints its result; returns the exit code. Only StackError is mapped, anything else is a bug and propagates. */
+export declare function runVerb({ label, name, io, argv, spec, run, code }: {
+    label: string;
+    name: string;
+    io: VerbIo;
+    argv: readonly string[];
+    spec: FlagSpec;
+    code?: string;
+    run: (ctx: VerbContext, flags: VerbFlags, positional: string[]) => VerbResult | Promise<VerbResult>;
+}): Promise<number>;
+/** The flags of each release action ({ boolean, value }): the parser refuses every other flag, and the usage of `starci app` is generated from them. */
+export declare const RELEASE_FLAGS: Readonly<{
+    [k: string]: FlagSpec;
+}>;
+/** Runs `starci app release <gate|push>`; `io` is the app IO (cwd, stdout, stderr, env, sops, stackIo). Returns the exit code. */
+export declare function releaseMain(argv: string[], io?: VerbIo): Promise<number>;

package/release/index.mjs

@@ -1,6 +1,6 @@
 // index.mjs - `starci app release <gate|push>` and the plumbing the release and database verbs share: the context built from the app's IO, strict flag
 // parsing, the optional `release:` / `database:` blocks of .starcistacks/application-stacks.yaml, text and --json output and the exit-code mapping.
-//   starci app release gate [--execute] [--sonar] [--source <ref>] [--tag-prefix <prefix>] [--backfill <tag>] [--json]
+//   starci app release gate [--execute] [--sha <ref>] [--tag-prefix <prefix>] [--backfill <tag>] [--json]
 //   starci app release push [--execute] [--remote <name>] [--urgent --reason <text>] [--json]
 // `harness` of the app IO ({ version, role, openTicket }) is what the starci CLI hands in: the caller's role an urgent record names and the ticket
 // queue a red back-fill files into.
@@ -17,101 +17,123 @@ import { EXIT, StackError, refusal } from '../stack/errors.mjs';
 import { RELEASE_CODE, VERSION, normalizeRelease, releaseGate } from './gate.mjs';
 import { releasePush } from './push.mjs';
 import { releaseUrgentPush } from './urgent.mjs';
-
 const IO_KEYS = ['cwd', 'stdout', 'stderr', 'env', 'sops', 'hostIdentity'];
-
 /** The stack context of one invocation: the IO of the app (cwd, writers, env, sops, hostIdentity) over the injectable seams of `io.stackIo` (spawn, sleep, now, fetch). */
 export function contextOf(io = {}) {
-  const own = Object.fromEntries(IO_KEYS.filter((key) => io[key] !== undefined).map((key) => [key, io[key]]));
-  return stackContext({ ...io.stackIo, ...own });
+    const own = Object.fromEntries(IO_KEYS.filter((key) => io[key] !== undefined).map((key) => [key, io[key]]));
+    return stackContext({ ...io.stackIo, ...own });
 }
-
 /** Splits argv into { flags, positional }; an unknown flag or a flag without its value is a refusal. */
 function parseVerbFlags(argv, spec, code = 'RELEASE_USAGE') {
-  const flags = {};
-  const positional = [];
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index];
-    if (spec.boolean.includes(arg)) flags[arg.slice(2)] = true;
-    else if (spec.value.includes(arg)) {
-      const value = argv[index + 1];
-      if (value === undefined || value.startsWith('--')) throw refusal(code, `${arg} needs a value`);
-      index += 1;
-      flags[arg.slice(2)] = value;
-    } else if (arg.startsWith('--')) throw refusal(code, `unknown flag ${arg}`);
-    else positional.push(arg);
-  }
-  return { flags, positional };
+    const flags = {};
+    const positional = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (spec.boolean.includes(arg))
+            flags[arg.slice(2)] = true;
+        else if (spec.value.includes(arg)) {
+            const value = argv[index + 1];
+            if (value === undefined || value.startsWith('--'))
+                throw refusal(code, `${arg} needs a value`);
+            index += 1;
+            flags[arg.slice(2)] = value;
+        }
+        else if (arg.startsWith('--'))
+            throw refusal(code, `unknown flag ${arg}`);
+        else
+            positional.push(arg);
+    }
+    return { flags, positional };
 }
-
 /** The top-level mapping of .starcistacks/application-stacks.yaml; a missing file is an empty declaration, an unreadable one a refusal. */
 export function readDeclaration(root) {
-  let source;
-  try { source = fs.readFileSync(path.join(root, STACKS_DIR, STACKS_FILE), 'utf8'); } catch { return {}; }
-  let doc;
-  try { doc = parseYaml(source); } catch { throw refusal('STACKS_DEPLOY_FILE_INVALID', `${STACKS_FILE} is not valid YAML`); }
-  return plain(doc) ? doc : {};
+    let source;
+    try {
+        source = fs.readFileSync(path.join(root, STACKS_DIR, STACKS_FILE), 'utf8');
+    }
+    catch {
+        return {};
+    }
+    let doc;
+    try {
+        doc = parseYaml(source);
+    }
+    catch {
+        throw refusal('STACKS_DEPLOY_FILE_INVALID', `${STACKS_FILE} is not valid YAML`);
+    }
+    return plain(doc) ? doc : {}; // reason: narrowed by the plain-object check above; YAML-parsed
 }
-
 function readPackage(root) {
-  try { return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')); } catch { throw refusal('RELEASE_PACKAGE_UNREADABLE', 'package.json is not readable JSON'); }
+    try {
+        return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    }
+    catch {
+        throw refusal('RELEASE_PACKAGE_UNREADABLE', 'package.json is not readable JSON');
+    }
 }
-
 /** The normalised `release:` block (tolerant of absence) with the package version: { root, version, gates, tagPrefix, defaultBranch, requireCi }. */
 export function loadReleaseConfig(root) {
-  const pkg = readPackage(root);
-  if (typeof pkg.version !== 'string' || !VERSION.test(pkg.version)) throw refusal(RELEASE_CODE, 'package.json needs a version like 1.2.3 (the release tag derives from it)');
-  const declaration = readDeclaration(root);
-  const { config, problems } = normalizeRelease(declaration.release, pkg.scripts, declaration.services, { example: isRuntimeExampleApp(root), entities: hasEntityList(root) });
-  if (!config) throw refusal(RELEASE_CODE, `${problems.length} problem(s) in release: ${problems.slice(0, 6).join('; ')}`);
-  return { root, version: pkg.version, ...config };
+    const pkg = readPackage(root);
+    if (typeof pkg.version !== 'string' || !VERSION.test(pkg.version))
+        throw refusal(RELEASE_CODE, 'package.json needs a version like 1.2.3 (the release tag derives from it)');
+    const declaration = readDeclaration(root);
+    const { config, problems } = normalizeRelease(declaration.release, pkg.scripts, declaration.services, { example: isRuntimeExampleApp(root), entities: hasEntityList(root) });
+    if (!config)
+        throw refusal(RELEASE_CODE, `${problems.length} problem(s) in release: ${problems.slice(0, 6).join('; ')}`);
+    return { root, version: pkg.version, ...config };
 }
-
 function print(ctx, name, flags, result) {
-  if (flags.json) ctx.stdout(`${JSON.stringify({ verb: name, ok: result.ok, ...result.data }, null, 2)}\n`);
-  else for (const line of result.lines ?? []) ctx.stdout(`${line}\n`);
+    if (flags.json)
+        ctx.stdout(`${JSON.stringify({ verb: name, ok: result.ok, ...result.data }, null, 2)}\n`);
+    else
+        for (const line of result.lines ?? [])
+            ctx.stdout(`${line}\n`);
 }
-
 /** Parses the flags, runs `run(ctx, flags, positional)` and prints its result; returns the exit code. Only StackError is mapped, anything else is a bug and propagates. */
 export async function runVerb({ label, name, io, argv, spec, run, code = 'RELEASE_USAGE' }) {
-  const ctx = contextOf(io);
-  try {
-    const { flags, positional } = parseVerbFlags(argv, spec, code);
-    const result = await run(ctx, flags, positional);
-    print(ctx, name, flags, result);
-    return result.ok ? EXIT.ok : EXIT.failed;
-  } catch (error) {
-    if (!(error instanceof StackError)) throw error;
-    ctx.stderr(`${label}: ${error.message}\n`);
-    return error.exit;
-  }
+    const ctx = contextOf(io);
+    try {
+        const { flags, positional } = parseVerbFlags(argv, spec, code);
+        const result = await run(ctx, flags, positional);
+        print(ctx, name, flags, result);
+        return result.ok ? EXIT.ok : EXIT.failed;
+    }
+    catch (error) {
+        if (!(error instanceof StackError))
+            throw error;
+        const refused = error; // narrowed by the instanceof check above (StackError is untyped until stack/ converts)
+        ctx.stderr(`${label}: ${refused.message}\n`);
+        return refused.exit;
+    }
 }
-
 const ACTIONS = {
-  gate: {
-    spec: { boolean: ['--execute', '--json', '--sonar'], value: ['--source', '--tag-prefix', '--backfill'] },
-    run: (ctx, flags, harness) => releaseGate(ctx, loadReleaseConfig(ctx.cwd), {
-      execute: flags.execute === true, sonar: flags.sonar === true, source: flags.source, tagPrefix: flags['tag-prefix'], backfill: flags.backfill, openTicket: harness?.openTicket,
-    }),
-  },
-  push: {
-    spec: { boolean: ['--execute', '--json', '--urgent'], value: ['--remote', '--reason', '--lint-baseline'] },
-    run: (ctx, flags, harness) => {
-      if (flags.reason !== undefined && flags.urgent !== true) throw refusal('RELEASE_USAGE', '--reason belongs to an urgent release (--urgent)');
-      if (flags['lint-baseline'] !== undefined && flags.urgent !== true) throw refusal('RELEASE_USAGE', '--lint-baseline belongs to an urgent release (--urgent)');
-      const config = loadReleaseConfig(ctx.cwd);
-      if (flags.urgent === true) return releaseUrgentPush(ctx, config, { execute: flags.execute === true, remote: flags.remote, reason: flags.reason, lintBaseline: flags['lint-baseline'], role: harness?.role ?? ctx.env.STARCI_ROLE });
-      return releasePush(ctx, config, { execute: flags.execute === true, remote: flags.remote });
+    gate: {
+        spec: { boolean: ['--execute', '--json'], value: ['--sha', '--tag-prefix', '--backfill'] },
+        run: (ctx, flags, harness) => releaseGate(ctx, loadReleaseConfig(ctx.cwd), {
+            execute: flags.execute === true, source: flags.sha, tagPrefix: flags['tag-prefix'], backfill: flags.backfill, openTicket: harness?.openTicket,
+        }),
+    },
+    push: {
+        spec: { boolean: ['--execute', '--json', '--urgent'], value: ['--remote', '--reason'] },
+        run: (ctx, flags, harness) => {
+            if (flags.reason !== undefined && flags.urgent !== true)
+                throw refusal('RELEASE_USAGE', '--reason belongs to an urgent release (--urgent)');
+            const config = loadReleaseConfig(ctx.cwd);
+            if (flags.urgent === true)
+                return releaseUrgentPush(ctx, config, { execute: flags.execute === true, remote: flags.remote, reason: flags.reason, role: harness?.role ?? ctx.env.STARCI_ROLE });
+            return releasePush(ctx, config, { execute: flags.execute === true, remote: flags.remote });
+        },
     },
-  },
 };
-
+/** The flags of each release action ({ boolean, value }): the parser refuses every other flag, and the usage of `starci app` is generated from them. */
+export const RELEASE_FLAGS = Object.freeze(Object.fromEntries(Object.entries(ACTIONS).map(([name, action]) => [name, action.spec])));
 /** Runs `starci app release <gate|push>`; `io` is the app IO (cwd, stdout, stderr, env, sops, stackIo). Returns the exit code. */
 export async function releaseMain(argv, io = {}) {
-  const action = Object.hasOwn(ACTIONS, argv[0]) ? ACTIONS[argv[0]] : null;
-  if (!action) {
-    contextOf(io).stderr('starci app release: takes gate or push\n');
-    return EXIT.refused;
-  }
-  return runVerb({ label: 'starci app release', name: argv[0], io, argv: argv.slice(1), spec: action.spec, run: (ctx, flags) => action.run(ctx, flags, io.harness) });
+    const first = argv[0];
+    const action = Object.hasOwn(ACTIONS, first) ? ACTIONS[first] ?? null : null;
+    if (!action) {
+        contextOf(io).stderr('starci app release: takes gate or push\n');
+        return EXIT.refused;
+    }
+    return runVerb({ label: 'starci app release', name: first, io, argv: argv.slice(1), spec: action.spec, run: (ctx, flags) => action.run(ctx, flags, io.harness) });
 }

package/release/lint-report.d.mts

@@ -0,0 +1,14 @@
+import type { VerbContext } from './index.mjs';
+/**
+ * Runs `starci app lint --side <side> --out <file>` for every side the app has, then writes reports/lint.sonar.json.
+ * `launch` turns an argv into [command, args] for the platform. Returns { pass, text }: the honest log of every lint run and the verdict.
+ * A lint that exits non-zero (findings or error) or writes no report fails the row; nothing is skipped.
+ */
+export declare function produceLintReports(ctx: VerbContext, { launch, platform, env }: {
+    launch: (argv: string[], platform: string) => [string, string[]];
+    platform: string;
+    env: NodeJS.ProcessEnv;
+}): {
+    pass: boolean;
+    text: string;
+};

package/release/lint-report.mjs

@@ -1,52 +1,53 @@
 // lint-report.mjs - the external issues report the release gate's sonar row produces before it runs the scanner.
-// The app declares `sonar.externalIssuesReportPaths=reports/lint.sonar.json`; the managed CI makes it with `lint --side <side> --sonar reports/lint.<side>.sonar.json`
+// The app declares `sonar.externalIssuesReportPaths=reports/lint.sonar.json`; the managed CI makes it with `lint --side <side> --out reports/lint.<side>.sonar.json`
 // per lint matrix side and a "merge Sonar lint reports" step. This module does the same locally, through the same process seam as every gate
 // (an argument array through ctx.spawn, never a shell). The merge below is the one in packages/hfs/sync/ci-commands.mjs (sonarMergeSteps): keep them identical.
 import fs from 'node:fs';
 import path from 'node:path';
 import { firstLine, tool } from '../stack/context.mjs';
-
 const LINT_SIDES = ['be', 'fe'];
 const MERGED_REPORT = 'reports/lint.sonar.json';
 const sideReport = (side) => `reports/lint.${side}.sonar.json`;
-
 /** CI merge: rules unique by id (last one wins, first position kept), issues concatenated in side order. */
 function mergeSonarReports(reports) {
-  const rules = [...new Map(reports.flatMap((report) => report.rules).map((rule) => [rule.id, rule])).values()];
-  const issues = reports.flatMap((report) => report.issues);
-  return { rules, issues };
+    const rules = [...new Map(reports.flatMap((report) => report.rules).map((rule) => [rule.id, rule])).values()];
+    const issues = reports.flatMap((report) => report.issues);
+    return { rules, issues };
 }
-
 /** The sides the app has: a be/ or fe/ folder beside the app root. */
 const sidesOf = (root) => LINT_SIDES.filter((side) => fs.existsSync(path.join(root, side)));
-
 /**
- * Runs `starci app lint --side <side> --sonar <file>` for every side the app has, then writes reports/lint.sonar.json.
+ * Runs `starci app lint --side <side> --out <file>` for every side the app has, then writes reports/lint.sonar.json.
  * `launch` turns an argv into [command, args] for the platform. Returns { pass, text }: the honest log of every lint run and the verdict.
  * A lint that exits non-zero (findings or error) or writes no report fails the row; nothing is skipped.
  */
 export function produceLintReports(ctx, { launch, platform, env }) {
-  const sides = sidesOf(ctx.cwd);
-  const out = [];
-  if (sides.length === 0) return { pass: false, text: `no be/ or fe/ side in ${ctx.cwd}: cannot produce ${MERGED_REPORT}\n` };
-  fs.mkdirSync(path.join(ctx.cwd, 'reports'), { recursive: true });
-  for (const side of sides) {
-    const file = path.join(ctx.cwd, sideReport(side));
-    fs.rmSync(file, { force: true });
-    const argv = ['npx', 'starci', 'app', 'lint', '--side', side, '--sonar', sideReport(side)];
-    const [command, args] = launch(argv, platform);
-    out.push(`$ ${argv.join(' ')}\n`);
-    const run = tool(ctx, command, args, { cwd: ctx.cwd, env });
-    out.push(`${run.stdout ?? ''}${run.stderr ?? ''}`);
-    if (run.error) return { pass: false, text: `${out.join('')}\nlint ${side} cannot run (${run.error.message})\n` };
-    if (run.status !== 0) return { pass: false, text: `${out.join('')}\nlint ${side} failed: exit ${run.status}; the scanner was not run\n` };
-    if (!fs.existsSync(file)) return { pass: false, text: `${out.join('')}\nlint ${side} wrote no ${sideReport(side)}; the scanner was not run\n` };
-  }
-  try {
-    const reports = sides.map((side) => JSON.parse(fs.readFileSync(path.join(ctx.cwd, sideReport(side)), 'utf8')));
-    fs.writeFileSync(path.join(ctx.cwd, MERGED_REPORT), `${JSON.stringify(mergeSonarReports(reports), null, 2)}\n`);
-  } catch (error) {
-    return { pass: false, text: `${out.join('')}\ncannot merge the side reports: ${firstLine(error.message)}\n` };
-  }
-  return { pass: true, text: `${out.join('')}\nwrote ${MERGED_REPORT} from ${sides.map(sideReport).join(', ')}\n\n` };
+    const sides = sidesOf(ctx.cwd);
+    const out = [];
+    if (sides.length === 0)
+        return { pass: false, text: `no be/ or fe/ side in ${ctx.cwd}: cannot produce ${MERGED_REPORT}\n` };
+    fs.mkdirSync(path.join(ctx.cwd, 'reports'), { recursive: true });
+    for (const side of sides) {
+        const file = path.join(ctx.cwd, sideReport(side));
+        fs.rmSync(file, { force: true });
+        const argv = ['npx', 'starci', 'app', 'lint', '--side', side, '--out', sideReport(side)];
+        const [command, args] = launch(argv, platform);
+        out.push(`$ ${argv.join(' ')}\n`);
+        const run = tool(ctx, command, args, { cwd: ctx.cwd, env });
+        out.push(`${run.stdout ?? ''}${run.stderr ?? ''}`);
+        if (run.error)
+            return { pass: false, text: `${out.join('')}\nlint ${side} cannot run (${run.error.message})\n` };
+        if (run.status !== 0)
+            return { pass: false, text: `${out.join('')}\nlint ${side} failed: exit ${run.status}; the scanner was not run\n` };
+        if (!fs.existsSync(file))
+            return { pass: false, text: `${out.join('')}\nlint ${side} wrote no ${sideReport(side)}; the scanner was not run\n` };
+    }
+    try {
+        const reports = sides.map((side) => JSON.parse(fs.readFileSync(path.join(ctx.cwd, sideReport(side)), 'utf8')));
+        fs.writeFileSync(path.join(ctx.cwd, MERGED_REPORT), `${JSON.stringify(mergeSonarReports(reports), null, 2)}\n`);
+    }
+    catch (error) {
+        return { pass: false, text: `${out.join('')}\ncannot merge the side reports: ${firstLine(error.message)}\n` };
+    }
+    return { pass: true, text: `${out.join('')}\nwrote ${MERGED_REPORT} from ${sides.map(sideReport).join(', ')}\n\n` };
 }

package/release/push.d.mts

@@ -0,0 +1,32 @@
+import type { ReleaseConfig } from './gate.mjs';
+import type { VerbContext, VerbResult } from './index.mjs';
+export declare function branchRefs(ctx: VerbContext, { head, remote, branch }: {
+    head: string;
+    remote: string;
+    branch: string;
+}, red: string[]): {
+    refs: string[];
+    tip: string | null;
+};
+export declare function tagRefs(ctx: VerbContext, { remote, tag }: {
+    remote: string;
+    tag: string;
+}, red: string[]): string[];
+export declare function probe(ctx: VerbContext, remote: string, refs: readonly string[], red: string[]): {
+    exit: number | null;
+    lines: string[];
+};
+export declare function assertNames(remote: unknown, branch: unknown): void;
+/**
+ * `starci app release push`. options: { execute, remote }. The remote and branch names are validated; the branch is the declared default branch.
+ * Dry run (and --execute) first prove the push with `git push --dry-run --atomic`; --execute then pushes for real, still through the hook.
+ */
+export declare function releasePush(ctx: VerbContext, config: ReleaseConfig, options?: {
+    execute?: boolean;
+    remote?: string | boolean | undefined;
+    candidateWait?: {
+        pollSeconds: number;
+        graceMinutes: number;
+        waitMinutes: number;
+    };
+}): Promise<VerbResult>;

package/release/push.mjs

@@ -11,114 +11,127 @@ import { firstLine } from '../stack/context.mjs';
 import { failure, refusal } from '../stack/errors.mjs';
 import { CI_NOT_REQUIRED, annotatedOnHead, git, refName, releaseDir } from './gate.mjs';
 import { candidateRef, candidateStep } from './candidate-ci.mjs';
-
 const VERDICT = /RIGHTS_PUSH_NOT_RELEASE|pre-push|failed to push|Everything up|->/u;
-
+// reason: the L4 record is JSON read from disk; greenRecord judges the fields it uses
 function readRecord(file) {
-  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
 }
-
 const greenRecord = (record, head, tag) => record?.head === head && record?.tag === tag
-  && Array.isArray(record.gates) && record.gates.length > 0 && record.gates.every((gate) => gate?.pass === true);
-
+    && Array.isArray(record.gates) && record.gates.length > 0 && record.gates.every((gate) => gate?.pass === true);
 /** The explicit release command gate: the annotated tag on HEAD whose L4 record names head and tag. Returns { tag } or { reason }. */
 function gateState(ctx, head, prefix, expected) {
-  const tags = annotatedOnHead(ctx, prefix);
-  if (!tags.includes(expected)) return { reason: `no ANNOTATED tag ${expected} (the package.json version) on HEAD${tags.length > 0 ? `, which carries ${tags.join(', ')}` : ''}: run starci app release gate --execute first` };
-  const file = path.join(releaseDir(ctx), `${head}.l4.json`);
-  if (!fs.existsSync(file)) return { reason: `no L4 record ${file}: run starci app release gate --execute first` };
-  const record = readRecord(file);
-  return greenRecord(record, head, expected) ? { tag: expected } : { reason: `the L4 record does not name head ${head.slice(0, 10)} and ${expected} with every gate green` };
+    const tags = annotatedOnHead(ctx, prefix);
+    if (!tags.includes(expected))
+        return { reason: `no ANNOTATED tag ${expected} (the package.json version) on HEAD${tags.length > 0 ? `, which carries ${tags.join(', ')}` : ''}: run starci app release gate --execute first` };
+    const file = path.join(releaseDir(ctx), `${head}.l4.json`);
+    if (!fs.existsSync(file))
+        return { reason: `no L4 record ${file}: run starci app release gate --execute first` };
+    const record = readRecord(file);
+    return greenRecord(record, head, expected) ? { tag: expected } : { reason: `the L4 record does not name head ${head.slice(0, 10)} and ${expected} with every gate green` };
 }
-
 /** The remote branch tip, or null on an empty remote; an unreachable remote is a failure (the state cannot be judged). */
 function remoteTip(ctx, remote, branch) {
-  const listed = git(ctx, ['ls-remote', '--heads', remote, branch], { allowFail: true });
-  if (listed.code !== 0) throw failure('RELEASE_REMOTE_UNREACHABLE', `cannot read ${remote}: ${firstLine(listed.stderr)}`);
-  if (listed.stdout === '') return null;
-  git(ctx, ['fetch', remote, branch, '--quiet']);
-  return listed.stdout.split(/\s/u)[0];
+    const listed = git(ctx, ['ls-remote', '--heads', remote, branch], { allowFail: true });
+    if (listed.code !== 0)
+        throw failure('RELEASE_REMOTE_UNREACHABLE', `cannot read ${remote}: ${firstLine(listed.stderr)}`);
+    if (listed.stdout === '')
+        return null;
+    git(ctx, ['fetch', remote, branch, '--quiet']);
+    return listed.stdout.split(/\s/u)[0];
 }
-
 const isAncestor = (ctx, older, newer) => git(ctx, ['merge-base', '--is-ancestor', older, newer], { allowFail: true }).code === 0;
-
 /** The remote object of a tag ('' when absent). */
 function remoteTagObject(ctx, remote, tag) {
-  const wanted = `refs/tags/${tag}`;
-  const listed = git(ctx, ['ls-remote', '--tags', remote, wanted], { allowFail: true }).stdout.split('\n');
-  return listed.map((line) => line.split('\t')).find((parts) => parts[1] === wanted)?.[0] ?? '';
+    const wanted = `refs/tags/${tag}`;
+    const listed = git(ctx, ['ls-remote', '--tags', remote, wanted], { allowFail: true }).stdout.split('\n');
+    return listed.map((line) => line.split('\t')).find((parts) => parts[1] === wanted)?.[0] ?? '';
 }
-
 export function branchRefs(ctx, { head, remote, branch }, red) {
-  const tip = remoteTip(ctx, remote, branch);
-  if (tip === null || isAncestor(ctx, tip, head)) return { refs: tip === head ? [] : [`${head}:refs/heads/${branch}`], tip };
-  if (isAncestor(ctx, head, tip)) return { refs: [], tip };
-  red.push(`${remote}/${branch} (${tip.slice(0, 10)}) is not an ancestor of HEAD: not a fast-forward; merge it first`);
-  return { refs: [], tip };
+    const tip = remoteTip(ctx, remote, branch);
+    if (tip === null || isAncestor(ctx, tip, head))
+        return { refs: tip === head ? [] : [`${head}:refs/heads/${branch}`], tip };
+    if (isAncestor(ctx, head, tip))
+        return { refs: [], tip };
+    red.push(`${remote}/${branch} (${tip.slice(0, 10)}) is not an ancestor of HEAD: not a fast-forward; merge it first`);
+    return { refs: [], tip };
 }
-
 export function tagRefs(ctx, { remote, tag }, red) {
-  const object = remoteTagObject(ctx, remote, tag);
-  if (object === '') return [`refs/tags/${tag}`];
-  if (object !== git(ctx, ['rev-parse', `refs/tags/${tag}`]).stdout) red.push(`tag ${tag} exists on ${remote} as a different object`);
-  return [];
+    const object = remoteTagObject(ctx, remote, tag);
+    if (object === '')
+        return [`refs/tags/${tag}`];
+    if (object !== git(ctx, ['rev-parse', `refs/tags/${tag}`]).stdout)
+        red.push(`tag ${tag} exists on ${remote} as a different object`);
+    return [];
 }
-
 export function probe(ctx, remote, refs, red) {
-  const run = git(ctx, ['push', '--dry-run', '--atomic', remote, ...refs], { allowFail: true });
-  const verdict = `${run.stderr}\n${run.stdout}`.split('\n').filter((line) => VERDICT.test(line)).slice(0, 4);
-  if (run.code !== 0) red.push('the pre-push hook refuses this push as things stand');
-  return { exit: run.code, lines: [`hook dry run  git push --dry-run --atomic: exit ${run.code}`, ...verdict.map((line) => `  ${line.slice(0, 200)}`)] };
+    const run = git(ctx, ['push', '--dry-run', '--atomic', remote, ...refs], { allowFail: true });
+    const verdict = `${run.stderr}\n${run.stdout}`.split('\n').filter((line) => VERDICT.test(line)).slice(0, 4);
+    if (run.code !== 0)
+        red.push('the pre-push hook refuses this push as things stand');
+    return { exit: run.code, lines: [`hook dry run  git push --dry-run --atomic: exit ${run.code}`, ...verdict.map((line) => `  ${line.slice(0, 200)}`)] };
 }
-
 const NAME_RULE = '^[A-Za-z0-9._/-]+$';
-
 export function assertNames(remote, branch) {
-  if (!refName(remote)) throw refusal('RELEASE_USAGE', `--remote ${remote} must match ${NAME_RULE}`);
-  if (!refName(branch)) throw refusal('RELEASE_USAGE', `the default branch ${branch} must match ${NAME_RULE}`);
+    if (!refName(remote))
+        throw refusal('RELEASE_USAGE', `--remote ${remote} must match ${NAME_RULE}`);
+    if (!refName(branch))
+        throw refusal('RELEASE_USAGE', `the default branch ${branch} must match ${NAME_RULE}`);
 }
-
 const gateLine = (gate) => (gate.tag ? `release gate   OK: annotated ${gate.tag} on HEAD, L4 record names head and tag` : 'release gate   CLOSED (see RED below)');
-
 /** A refusal result: the lines so far, every red item and a closing line; `data.red` lists the red items. */
 const refuse = (out, red, data, closing) => ({ ok: false, lines: [...out, ...red.map((item) => `RED: ${item}`), closing], data: { ...data, red } });
-
 /**
  * `starci app release push`. options: { execute, remote }. The remote and branch names are validated; the branch is the declared default branch.
  * Dry run (and --execute) first prove the push with `git push --dry-run --atomic`; --execute then pushes for real, still through the hook.
  */
 export async function releasePush(ctx, config, options = {}) {
-  const remote = options.remote ?? 'origin';
-  const branch = config.defaultBranch;
-  assertNames(remote, branch);
-  const head = git(ctx, ['rev-parse', 'HEAD']).stdout;
-  const gate = gateState(ctx, head, config.tagPrefix, `${config.tagPrefix}${config.version}`);
-  const out = [`HEAD           ${head}`, gateLine(gate)];
-  const data = { head, tag: gate.tag ?? null, remote, branch, refs: [], hook: null, pushed: false };
-  if (!gate.tag) return refuse(out, [gate.reason], data, 'nothing pushed.');
-  const red = [];
-  const refs = [...branchRefs(ctx, { head, remote, branch }, red).refs, ...tagRefs(ctx, { remote, tag: gate.tag }, red)];
-  data.refs = refs;
-  const requireCi = config.requireCi === true;
-  const candidate = refs.length > 0 && requireCi ? candidateRef(gate.tag, config.tagPrefix) : null;
-  if (candidate) out.push(`plan           git push ${remote} +${head.slice(0, 10)}:${candidate}, wait for its ci.yml run to be green, then git push --atomic ${remote} ${refs.join(' ')}`);
-  else if (refs.length > 0) out.push(`plan           git push --atomic ${remote} ${refs.join(' ')}`, `ci             ${CI_NOT_REQUIRED}`);
-  else out.push(`plan           git push --atomic ${remote} (nothing)`);
-  if (refs.length === 0 && red.length === 0) return { ok: true, lines: [...out, `already pushed: ${remote}/${branch} holds HEAD and ${gate.tag} is on ${remote}. Nothing to do.`], data };
-  if (refs.length > 0) {
-    const hook = probe(ctx, remote, refs, red);
-    data.hook = { exit: hook.exit };
-    out.push(...hook.lines);
-  }
-  if (red.length > 0) return refuse(out, red, data, options.execute === true ? 'nothing pushed.' : 'dry run: nothing pushed.');
-  if (options.execute !== true) return { ok: true, lines: [...out, 'dry run: nothing pushed. ready; re-run with --execute.'], data };
-  if (requireCi) {
-    const judged = await candidateStep(ctx, { head, tag: gate.tag, prefix: config.tagPrefix, remote, wait: options.candidateWait });
-    data.candidate = judged.data;
-    out.push(...judged.lines);
-    if (!judged.ok) return { ok: false, lines: [...out, `nothing pushed to ${branch} or ${gate.tag}.`], data };
-  } else data.candidate = { required: false, note: CI_NOT_REQUIRED };
-  const run = git(ctx, ['push', '--atomic', remote, ...refs], { allowFail: true });
-  if (run.code !== 0) return { ok: false, lines: [...out, `push failed: ${firstLine(run.stderr)}`], data };
-  return { ok: true, lines: [...out, `pushed to ${remote}: ${refs.join(' ')}`], data: { ...data, pushed: true } };
+    const remote = (options.remote ?? 'origin');
+    const branch = config.defaultBranch;
+    assertNames(remote, branch);
+    const head = git(ctx, ['rev-parse', 'HEAD']).stdout;
+    const gate = gateState(ctx, head, config.tagPrefix, `${config.tagPrefix}${config.version}`);
+    const out = [`HEAD           ${head}`, gateLine(gate)];
+    const data = { head, tag: gate.tag ?? null, remote, branch, refs: [], hook: null, pushed: false }; // reason: the --json answer of the verb; fields are added as the push proceeds
+    if (!gate.tag)
+        return refuse(out, [gate.reason], data, 'nothing pushed.');
+    const red = [];
+    const refs = [...branchRefs(ctx, { head, remote, branch }, red).refs, ...tagRefs(ctx, { remote, tag: gate.tag }, red)];
+    data.refs = refs;
+    const requireCi = config.requireCi === true;
+    const candidate = refs.length > 0 && requireCi ? candidateRef(gate.tag, config.tagPrefix) : null;
+    if (candidate)
+        out.push(`plan           git push ${remote} +${head.slice(0, 10)}:${candidate}, wait for its ci.yml run to be green, then git push --atomic ${remote} ${refs.join(' ')}`);
+    else if (refs.length > 0)
+        out.push(`plan           git push --atomic ${remote} ${refs.join(' ')}`, `ci             ${CI_NOT_REQUIRED}`);
+    else
+        out.push(`plan           git push --atomic ${remote} (nothing)`);
+    if (refs.length === 0 && red.length === 0)
+        return { ok: true, lines: [...out, `already pushed: ${remote}/${branch} holds HEAD and ${gate.tag} is on ${remote}. Nothing to do.`], data };
+    if (refs.length > 0) {
+        const hook = probe(ctx, remote, refs, red);
+        data.hook = { exit: hook.exit };
+        out.push(...hook.lines);
+    }
+    if (red.length > 0)
+        return refuse(out, red, data, options.execute === true ? 'nothing pushed.' : 'dry run: nothing pushed.');
+    if (options.execute !== true)
+        return { ok: true, lines: [...out, 'dry run: nothing pushed. ready; re-run with --execute.'], data };
+    if (requireCi) {
+        const judged = await candidateStep(ctx, { head, tag: gate.tag, prefix: config.tagPrefix, remote, wait: options.candidateWait });
+        data.candidate = judged.data;
+        out.push(...judged.lines);
+        if (!judged.ok)
+            return { ok: false, lines: [...out, `nothing pushed to ${branch} or ${gate.tag}.`], data };
+    }
+    else
+        data.candidate = { required: false, note: CI_NOT_REQUIRED };
+    const run = git(ctx, ['push', '--atomic', remote, ...refs], { allowFail: true });
+    if (run.code !== 0)
+        return { ok: false, lines: [...out, `push failed: ${firstLine(run.stderr)}`], data };
+    return { ok: true, lines: [...out, `pushed to ${remote}: ${refs.join(' ')}`], data: { ...data, pushed: true } };
 }