@starci/hfs 4.3.0 → 4.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.3.0",
+  "version": "4.4.1",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",
@@ -18,6 +18,9 @@
     "LICENSE",
     "src/main.mjs",
     "emit/**",
+    "stack/**",
+    "release/**",
+    "db/**",
     "lint/**",
     "scaffold/**",
     "report/**",

package/release/gate.mjs

@@ -0,0 +1,298 @@
+// gate.mjs - `starci app release gate`: the honest release gate. It runs the app's own gates on a clean HEAD and ONLY when every one is green it
+// writes the L4 record <git-common-dir>/starci-release/<HEAD sha>.l4.json (head, tag, per-gate log path and sha256) and creates the annotated tag.
+// The canon pre-push hook lets main and v* tags through only for a HEAD with that tag and that record. Nothing is pushed here (see push.mjs).
+// The gate list comes from the optional `release:` block of .starcistacks/application-stacks.yaml, else from the app's managed package scripts.
+// Commands are argument arrays (never shell strings) run through ctx.spawn; a git tool call always goes through the same seam.
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { isPlainObject as plain } from '../runtime/engine/plain-object.mjs';
+import { firstLine, lines, tool } from '../stack/context.mjs';
+import { failure, refusal } from '../stack/errors.mjs';
+
+export const RELEASE_CODE = 'RELEASE_CONFIG_INVALID';
+
+const FIELDS = new Set(['gates', 'tagPrefix', 'defaultBranch', 'tagMatchesVersion']);
+const GATE_FIELDS = new Set(['name', 'command', 'summary', 'env']);
+const GATE_NAME = /^[a-z][a-z0-9-]*$/u;
+const TOKEN = /^[A-Za-z0-9_@%+=:,./\\-]+$/u;
+const ENV_KEY = /^[A-Z][A-Z0-9_]*$/u;
+const REF_NAME = /^[A-Za-z0-9._/][A-Za-z0-9._/-]*$/u;
+const PREFIX = /^[A-Za-z][A-Za-z0-9._-]{0,19}$/u;
+export const VERSION = /^(\d+)\.(\d+)\.(\d+)$/u;
+const THRESHOLD_MISS = /coverage threshold .* not met/gu;
+const WRAPPED = new Set(['npm', 'npx']);
+const SCRIPT_GATES = ['typecheck', 'build:be', 'lint', 'build:fe', 'test'];
+const MAX_PATCH = 100;
+
+/** True for a branch or remote name git can take as one argument (no leading dash, only path-like characters). */
+export const refName = (value) => typeof value === 'string' && REF_NAME.test(value);
+
+const scriptGate = (script) => ({
+  name: script.replaceAll(':', '-'),
+  command: ['npm', 'run', script],
+  summary: script === 'test' ? 'jest' : null,
+  env: {},
+});
+
+/** The gates derived from the managed package scripts: the app check first, then every script the sync renders that the app has. */
+function defaultGates(scripts) {
+  const present = SCRIPT_GATES.filter((script) => typeof scripts?.[script] === 'string');
+  return [{ name: 'app-check', command: ['npx', 'starci', 'app', 'check'], summary: null, env: {} }, ...present.map(scriptGate)];
+}
+
+function gateProblems(entry, at, seen) {
+  const found = [];
+  for (const key of Object.keys(entry)) if (!GATE_FIELDS.has(key)) found.push(`${at}.${key}: is not a field of a gate`);
+  if (typeof entry.name !== 'string' || !GATE_NAME.test(entry.name)) found.push(`${at}.name: must match ${GATE_NAME}`);
+  else if (seen.has(entry.name)) found.push(`${at}.name: ${entry.name} is declared twice`);
+  const command = entry.command;
+  if (!Array.isArray(command) || command.length === 0 || !command.every((word) => typeof word === 'string' && TOKEN.test(word))) found.push(`${at}.command: must be a non-empty list of plain words (no shell strings)`);
+  if (entry.summary !== undefined && entry.summary !== 'jest') found.push(`${at}.summary: must be jest`);
+  const env = entry.env ?? {};
+  if (!plain(env) || !Object.entries(env).every(([key, value]) => ENV_KEY.test(key) && typeof value === 'string')) found.push(`${at}.env: must map UPPER_CASE names to string values`);
+  return found;
+}
+
+function gatesOf(list, problems) {
+  if (!Array.isArray(list) || list.length === 0) {
+    problems.push('release.gates: must be a non-empty list');
+    return [];
+  }
+  const seen = new Set();
+  const gates = [];
+  list.forEach((entry, index) => {
+    const at = `release.gates[${index}]`;
+    const found = plain(entry) ? gateProblems(entry, at, seen) : [`${at}: must be a mapping`];
+    problems.push(...found);
+    if (found.length === 0) {
+      seen.add(entry.name);
+      gates.push({ name: entry.name, command: entry.command, summary: entry.summary ?? null, env: entry.env ?? {} });
+    }
+  });
+  return gates;
+}
+
+/** Judges the optional `release:` block. Absence is fine (defaults). Returns { config } or { problems }. */
+export function normalizeRelease(block, scripts = {}) {
+  const raw = block ?? {};
+  if (!plain(raw)) return { problems: ['release: must be a mapping'] };
+  const problems = Object.keys(raw).filter((key) => !FIELDS.has(key)).map((key) => `release.${key}: is not a field of the release block`);
+  const tagPrefix = raw.tagPrefix ?? 'v';
+  const defaultBranch = raw.defaultBranch ?? 'main';
+  const tagMatchesVersion = raw.tagMatchesVersion ?? false;
+  if (typeof tagPrefix !== 'string' || !PREFIX.test(tagPrefix)) problems.push(`release.tagPrefix: must match ${PREFIX}`);
+  if (!refName(defaultBranch)) problems.push(`release.defaultBranch: must match ${REF_NAME}`);
+  if (typeof tagMatchesVersion !== 'boolean') problems.push('release.tagMatchesVersion: must be true or false');
+  const gates = raw.gates === undefined ? defaultGates(scripts) : gatesOf(raw.gates, problems);
+  return problems.length === 0 ? { config: { gates, tagPrefix, defaultBranch, tagMatchesVersion } } : { problems };
+}
+
+/* ---- git through the seam */
+
+/** Runs git in the app root; a missing git or (unless allowFail) a non-zero exit is a failure whose message names the first stderr line. */
+export function git(ctx, args, { allowFail = false } = {}) {
+  const run = tool(ctx, 'git', args, { cwd: ctx.cwd });
+  if (run.error) throw failure('RELEASE_GIT_MISSING', `cannot run git (${run.error.message})`);
+  if (run.status !== 0 && !allowFail) throw failure('RELEASE_GIT_FAILED', `git ${args.slice(0, 2).join(' ')}: ${firstLine(run.stderr)}`);
+  return { code: run.status, stdout: String(run.stdout ?? '').trim(), stderr: String(run.stderr ?? '') };
+}
+
+/** The directory that holds the L4 records: <git common dir>/starci-release. */
+export const releaseDir = (ctx) => path.join(path.resolve(ctx.cwd, git(ctx, ['rev-parse', '--git-common-dir']).stdout), 'starci-release');
+
+/** Annotated tags `<prefix><digit>*` that point at HEAD (lightweight tags do not count: the hook ignores them). */
+export function annotatedOnHead(ctx, prefix) {
+  const names = lines(git(ctx, ['tag', '--points-at', 'HEAD', '--list', `${prefix}[0-9]*`]).stdout);
+  return names.filter((name) => git(ctx, ['cat-file', '-t', `refs/tags/${name}`], { allowFail: true }).stdout === 'tag');
+}
+
+const dirtyPaths = (ctx) => lines(git(ctx, ['status', '--porcelain', '--untracked-files=normal']).stdout);
+
+/** Tag names that exist locally or on the remote. */
+function takenTags(ctx, prefix, remote) {
+  const local = lines(git(ctx, ['tag', '--list', `${prefix}*`]).stdout);
+  const listed = lines(git(ctx, ['ls-remote', '--tags', remote], { allowFail: true }).stdout);
+  const remoteNames = listed.map((line) => line.split('refs/tags/')[1]?.replace(/\^\{\}$/u, '')).filter(Boolean);
+  return new Set([...local, ...remoteNames]);
+}
+
+/** Next free `<prefix><major>.<minor>.<n>` for the package version. */
+function nextFree(prefix, version, taken) {
+  const [, major, minor] = VERSION.exec(version);
+  for (let patch = 0; patch < MAX_PATCH; patch += 1) {
+    const candidate = `${prefix}${major}.${minor}.${patch}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+  throw refusal('RELEASE_NO_FREE_TAG', `no free tag ${prefix}${major}.${minor}.0 to ${prefix}${major}.${minor}.${MAX_PATCH - 1}`);
+}
+
+/** The tag this release uses and its state: on-head (reused), free (will be created) or taken (exists on another commit). */
+function chooseTag(ctx, config, { prefix, remote }) {
+  const onHead = annotatedOnHead(ctx, prefix);
+  const taken = takenTags(ctx, prefix, remote);
+  const exact = `${prefix}${config.version}`;
+  const tag = config.tagMatchesVersion ? exact : (onHead[0] ?? nextFree(prefix, config.version, taken));
+  if (onHead.includes(tag)) return { tag, state: 'on-head' };
+  return { tag, state: taken.has(tag) ? 'taken' : 'free' };
+}
+
+/* ---- gate results */
+
+const sha256 = (file) => createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+
+const lineAfter = (text, label) => {
+  const found = text.split('\n').find((line) => line.startsWith(label));
+  return found === undefined ? null : found.slice(label.length).trim();
+};
+
+/** The jest summary lines of a log: { suites, failedSuites, tests, failed, passed } or null when jest printed none. */
+function jestSummary(text) {
+  const suites = lineAfter(text, 'Test Suites:');
+  const tests = lineAfter(text, 'Tests:');
+  if (suites === null || tests === null) return null;
+  const count = (line, word) => Number(new RegExp(String.raw`(\d+) ${word}`, 'u').exec(line)?.[1] ?? 0);
+  return {
+    suites: count(suites, 'total'), failedSuites: count(suites, 'failed'),
+    tests: count(tests, 'total'), failed: count(tests, 'failed'), passed: count(tests, 'passed'),
+  };
+}
+
+/** Judges a jest-style gate from its log: green needs suites that all passed, every test passed and no coverage threshold miss. */
+function judgeJest(text) {
+  const summary = jestSummary(text);
+  const misses = (text.match(THRESHOLD_MISS) ?? []).length;
+  if (!summary) return { pass: false, detail: 'no jest summary in the log', summary: null, misses };
+  const pass = summary.suites > 0 && summary.failedSuites === 0 && summary.failed === 0 && summary.passed === summary.tests && misses === 0;
+  const detail = `suites ${summary.suites - summary.failedSuites}/${summary.suites}, tests ${summary.passed}/${summary.tests}, coverage-threshold misses ${misses}`;
+  return { pass, detail, summary, misses };
+}
+
+/** [command, args] to start an argv; on Windows npm and npx are .cmd files, so they start through cmd.exe (words are validated, never a shell string). */
+export function launch(argv, platform) {
+  if (platform === 'win32' && WRAPPED.has(argv[0])) return ['cmd.exe', ['/d', '/s', '/c', ...argv]];
+  return [argv[0], argv.slice(1)];
+}
+
+function runGate(ctx, gate, { dir, platform }) {
+  const log = path.join(dir, `${gate.name}.log`);
+  const started = ctx.now();
+  const [command, args] = launch(gate.command, platform);
+  const run = tool(ctx, command, args, { cwd: ctx.cwd, env: { ...ctx.env, ...gate.env } });
+  const text = `${run.stdout ?? ''}${run.stderr ?? ''}`;
+  fs.writeFileSync(log, text);
+  const verdict = judgeVerdict(run, gate, text);
+  const seconds = Math.round((ctx.now() - started) / 1000);
+  return {
+    name: gate.name, command: gate.command.join(' '), pass: verdict.pass, detail: verdict.detail, seconds,
+    summary: verdict.summary ?? null, log: path.resolve(log), logSha256: sha256(log), env: Object.keys(gate.env),
+  };
+}
+
+function judgeVerdict(run, gate, text) {
+  if (run.error) return { pass: false, detail: `cannot run (${run.error.message})` };
+  if (run.status !== 0) return { pass: false, detail: `exit ${run.status}` };
+  if (gate.summary === 'jest') return judgeJest(text);
+  return { pass: true, detail: 'exit 0' };
+}
+
+/* ---- the gate */
+
+function sourceProblem(ctx, source, head) {
+  if (source === 'HEAD') return null;
+  if (!refName(source)) return `--source ${source} is not a ref name`;
+  const resolved = git(ctx, ['rev-parse', '--verify', `${source}^{commit}`], { allowFail: true });
+  if (resolved.code !== 0) return `cannot resolve --source ${source}`;
+  if (resolved.stdout !== head) return `--source ${source} is ${resolved.stdout.slice(0, 10)} but HEAD is ${head.slice(0, 10)}: the hook and the L4 record are about HEAD; check the candidate out first`;
+  return null;
+}
+
+function tagLine({ tag, state }) {
+  if (state === 'on-head') return `tag            ${tag} (annotated, already on HEAD)`;
+  if (state === 'taken') return `tag            ${tag} (TAKEN by another commit)`;
+  return `tag            ${tag} (free: will be created, annotated)`;
+}
+
+/** Everything that can be known without running a gate: the facts, the red preconditions and the lines that describe them. */
+function inspect(ctx, config, options) {
+  const head = git(ctx, ['rev-parse', 'HEAD']).stdout;
+  const branch = git(ctx, ['rev-parse', '--abbrev-ref', 'HEAD'], { allowFail: true }).stdout;
+  const out = [`checkout       ${ctx.cwd}`, `HEAD           ${head} (${branch})`];
+  const red = [];
+  const problem = sourceProblem(ctx, options.source ?? 'HEAD', head);
+  if (problem) red.push(problem);
+  const dirty = dirtyPaths(ctx);
+  if (dirty.length > 0) red.push(`working tree is not clean (${dirty.length} path(s), first: ${dirty[0].slice(0, 100)}): the record would vouch for files that are not in HEAD`);
+  else out.push('worktree       clean');
+  const prefix = options.tagPrefix ?? config.tagPrefix;
+  if (!PREFIX.test(prefix)) throw refusal('RELEASE_USAGE', `--tag-prefix must match ${PREFIX}`);
+  const chosen = chooseTag(ctx, config, { prefix, remote: 'origin' });
+  if (chosen.state === 'taken') red.push(`tag ${chosen.tag} already exists on another commit (local or remote)`);
+  out.push(tagLine(chosen));
+  return { head, chosen, red, out };
+}
+
+function planLines(config, facts, dir, recordPath) {
+  const out = [`L4 record      ${recordPath}`, `logs           ${dir}`, '', 'gates (all must pass, in this order):'];
+  for (const gate of config.gates) {
+    const summary = gate.summary ? ` (summary: ${gate.summary})` : '';
+    out.push(`  ${gate.name.padEnd(17)} ${gate.command.join(' ')}${summary}`);
+  }
+  out.push(`then: write ${path.basename(recordPath)} and \`git tag -a ${facts.chosen.tag}\` on ${facts.head.slice(0, 10)}; push it with \`starci app release push\`.`);
+  return out;
+}
+
+function assertUnmoved(ctx, head) {
+  const now = git(ctx, ['rev-parse', 'HEAD']).stdout;
+  if (now !== head) throw failure('RELEASE_HEAD_MOVED', `HEAD moved during the gates (${head.slice(0, 10)} -> ${now.slice(0, 10)}). No record.`);
+  const dirty = dirtyPaths(ctx);
+  if (dirty.length > 0) throw failure('RELEASE_TREE_DIRTY', `the gates left ${dirty.length} changed or untracked path(s) (first: ${dirty[0].slice(0, 100)}): generated files differ from HEAD. Commit or ignore them properly, then rerun. No record.`);
+}
+
+function writeRecord(ctx, { head, tag, results, recordPath }) {
+  const record = {
+    schema: 'starci-app-l4-record/1', head, tag, createdAt: new Date(ctx.now()).toISOString(), producedBy: 'starci app release gate',
+    note: 'The full gates ran on a clean HEAD; every entry links the real log and its sha256.',
+    gates: results,
+  };
+  fs.mkdirSync(path.dirname(recordPath), { recursive: true });
+  fs.writeFileSync(recordPath, `${JSON.stringify(record, null, 2)}\n`);
+}
+
+function runAll(ctx, config, { dir, platform }) {
+  fs.mkdirSync(dir, { recursive: true });
+  const results = [];
+  for (const gate of config.gates) {
+    const result = runGate(ctx, gate, { dir, platform });
+    results.push(result);
+    if (!result.pass) break;
+  }
+  return results;
+}
+
+const summaryOf = (result) => `${result.pass ? 'PASS' : 'FAIL'} ${result.name} (${result.detail}, ${result.seconds}s) log ${result.log}`;
+
+/**
+ * `starci app release gate`: dry run prints the preconditions, the gate list, the head and the tag; --execute runs every gate and, only if all are green,
+ * writes the L4 record and creates the annotated tag. options: { execute, source, tagPrefix, platform }.
+ */
+export async function releaseGate(ctx, config, options = {}) {
+  const facts = inspect(ctx, config, options);
+  const common = releaseDir(ctx);
+  const recordPath = path.join(common, `${facts.head}.l4.json`);
+  const dir = path.join(common, facts.head.slice(0, 12));
+  const plan = [...facts.out, ...planLines(config, facts, dir, recordPath)];
+  const base = { head: facts.head, tag: facts.chosen.tag, record: recordPath, gates: config.gates.map((gate) => gate.name) };
+  if (facts.red.length > 0) return { ok: false, lines: [...plan, ...facts.red.map((item) => `RED: ${item}`), 'nothing was run.'], data: { ...base, red: facts.red, executed: false } };
+  if (options.execute !== true) return { ok: true, lines: [...plan, '', 'dry run: no gate was run, nothing written. preconditions OK.'], data: { ...base, red: [], executed: false } };
+  const results = runAll(ctx, config, { dir, platform: options.platform ?? process.platform });
+  const report = results.map(summaryOf);
+  const failed = results.filter((result) => !result.pass);
+  if (failed.length > 0) return { ok: false, lines: [...plan, ...report, `gate(s) red: ${failed.map((item) => item.name).join(', ')}. No L4 record, no tag.`], data: { ...base, executed: true, results } };
+  assertUnmoved(ctx, facts.head);
+  writeRecord(ctx, { head: facts.head, tag: facts.chosen.tag, results, recordPath });
+  const created = facts.chosen.state !== 'on-head';
+  if (created) git(ctx, ['tag', '-a', facts.chosen.tag, '-m', `release ${facts.chosen.tag}: gates green on ${facts.head.slice(0, 12)} (L4 record ${path.basename(recordPath)})`, facts.head]);
+  const tagged = created ? `annotated tag ${facts.chosen.tag} created on ${facts.head.slice(0, 10)}` : `annotated tag ${facts.chosen.tag} already on ${facts.head.slice(0, 10)}`;
+  return { ok: true, lines: [...plan, ...report, `L4 record written: ${recordPath}`, tagged], data: { ...base, executed: true, results, tagCreated: created } };
+}

package/release/index.mjs

@@ -0,0 +1,103 @@
+// 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] [--source <ref>] [--tag-prefix <prefix>] [--json]
+//   starci app release push [--execute] [--remote <name>] [--json]
+// Every action is a dry run unless --execute is given. A refusal is a StackError (exit 2); a failed step returns ok false (exit 1).
+import fs from 'node:fs';
+import path from 'node:path';
+import { isPlainObject as plain } from '../runtime/engine/plain-object.mjs';
+import { parseYaml } from '../runtime/engine/yaml.mjs';
+import { STACKS_DIR, STACKS_FILE } from '../stack/config.mjs';
+import { stackContext } from '../stack/context.mjs';
+import { EXIT, StackError, refusal } from '../stack/errors.mjs';
+import { RELEASE_CODE, VERSION, normalizeRelease, releaseGate } from './gate.mjs';
+import { releasePush } from './push.mjs';
+
+const IO_KEYS = ['cwd', 'stdout', 'stderr', 'env', 'sops'];
+
+/** The stack context of one invocation: the IO of the app (cwd, writers, env, sops) 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 });
+}
+
+/** 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 };
+}
+
+/** 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 : {};
+}
+
+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'); }
+}
+
+/** The normalised `release:` block (tolerant of absence) with the package version: { root, version, gates, tagPrefix, defaultBranch, tagMatchesVersion }. */
+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 { config, problems } = normalizeRelease(readDeclaration(root).release, pkg.scripts);
+  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`);
+}
+
+/** 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 ACTIONS = {
+  gate: {
+    spec: { boolean: ['--execute', '--json'], value: ['--source', '--tag-prefix'] },
+    run: (ctx, flags) => releaseGate(ctx, loadReleaseConfig(ctx.cwd), { execute: flags.execute === true, source: flags.source, tagPrefix: flags['tag-prefix'] }),
+  },
+  push: {
+    spec: { boolean: ['--execute', '--json'], value: ['--remote'] },
+    run: (ctx, flags) => releasePush(ctx, loadReleaseConfig(ctx.cwd), { execute: flags.execute === true, remote: flags.remote }),
+  },
+};
+
+/** 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: action.run });
+}

package/release/push.mjs

@@ -0,0 +1,110 @@
+// push.mjs - `starci app release push`: sends the default branch and the release tag to the remote in ONE atomic push through the repository's own
+// pre-push hook (never --no-verify). It requires what the hook requires: an annotated release tag on HEAD and the L4 record of the gate for that
+// head and tag. `git push --dry-run --atomic` always runs first (the hook's verdict is the proof) and any failure refuses the push.
+import fs from 'node:fs';
+import path from 'node:path';
+import { firstLine } from '../stack/context.mjs';
+import { failure, refusal } from '../stack/errors.mjs';
+import { annotatedOnHead, git, refName, releaseDir } from './gate.mjs';
+
+const VERDICT = /RIGHTS_PUSH_NOT_RELEASE|pre-push|failed to push|Everything up|->/u;
+
+function readRecord(file) {
+  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);
+
+/** The release gate as the hook reads it: the annotated tag on HEAD whose L4 record names head and tag. Returns { tag } or { reason }. */
+function gateState(ctx, head, prefix) {
+  const tags = annotatedOnHead(ctx, prefix);
+  if (tags.length === 0) return { reason: `no ANNOTATED tag ${prefix}[0-9]* on HEAD: 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);
+  const tag = tags.find((name) => greenRecord(record, head, name));
+  return tag ? { tag } : { reason: `the L4 record does not name head ${head.slice(0, 10)} and one of ${tags.join(', ')} 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 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] ?? '';
+}
+
+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 };
+}
+
+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 [];
+}
+
+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 NAME_RULE = '^[A-Za-z0-9._/-]+$';
+
+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}`);
+}
+
+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);
+  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;
+  out.push(`plan           git push --atomic ${remote} ${refs.join(' ') || '(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 };
+  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 } };
+}

package/report/sonar.mjs

@@ -50,7 +50,7 @@ export function mergeReports(reports) {
  * indexes, and a finding about hfs.json, a workflow, a config file or a directory is not on one, so it is filed on this
  * file and its message names the real path. Null when the tracked tree has no source file.
  */
-export function anchorOf(tracked, sourceRoots) {
+function anchorOf(tracked, sourceRoots) {
   const roots = sourceRoots.map((root) => `${posix(root).replace(/\/$/, '')}/`);
   return [...tracked].map(posix).filter((file) => SOURCE_FILE.test(file) && roots.some((root) => file.startsWith(root))).sort(cmp)[0] ?? null;
 }

package/runtime/config.example.yaml

@@ -185,10 +185,11 @@ sonar: {organization: null}
 #   minFreeRamPct  free-RAM percentage below which no new heavy op starts
 # set them only in the gitignored config.yaml copy, e.g.
 #   resources: {minFreeDiskGb: 5, minFreeDiskPct: 1, minFreeRamPct: 10}
-# release — where the full test suite of a release is judged (scripts/guards/release-suite-mode.mjs; docs/releasing.md "Where the suite runs"). One key:
-#   suite: local   the shipped default: `starci release cut` runs the root suite and the Linux parity container before it pushes, and the pre-push gate asks for their green rows
-#   suite: ci      the owner's recorded choice (2026-10-09): no local full suite and no Linux container; the GitHub ci workflow runs the suite (with coverage, Codecov, SonarCloud) AFTER the push.
-#                  The cut still runs npm run check, npm run test:packages, the specs affected by the release, the live Orca smokes and the example apps; the record lists the root suite as
-#                  delegated, never green. A release can reach GitHub and its tag before the suite has run; a red CI is fixed forward with the next pre-release (starci release ci-status).
-# "none" is refused: the suite does not vanish, it moves to CI. Set it only in the gitignored config.yaml copy: release: {suite: ci}
+# release - where the Linux parity of a release is judged (scripts/guards/release-suite-mode.mjs; docs/releasing.md "Where the suite runs"). One key:
+#   suite: local   the shipped default: `starci release cut` runs the root rows (npm run test:packages, npm run test:e2e, npm run check) and the Linux parity container before it pushes,
+#                  and the pre-push gate asks for the green root rows
+#   suite: ci      the owner's recorded choice (2026-10-09): no local Linux container; the GitHub ci workflow runs the Linux parity (and SonarCloud) AFTER the push.
+#                  The cut still runs the same root rows and the example apps; the record lists linux-parity as delegated, never green.
+#                  A release can reach GitHub and its tag before the Linux parity has run; a red CI is fixed forward with the next pre-release (starci release ci-status).
+# "none" is refused: the Linux parity does not vanish, it moves to CI. Set it only in the gitignored config.yaml copy: release: {suite: ci}
 release: {suite: local}