@starci/hfs 4.4.1 → 4.5.1

package/emit/db-types.mjs

@@ -8,7 +8,8 @@
  * schemas `supabase/config.toml` declares under [api]; the CLI reaches Docker, so nothing here runs inside a check that has
  * no stack. `run` is the command runner - `(file, args, {cwd})` answering the spawnSync result `{status, stdout, stderr}` -
  * the default spawns the `supabase` binary with an argument array, never a shell string and never printing env; a spec's fake
- * keeps Docker out of the suite. A run that cannot produce the text throws DbTypesError (HFS_EMIT_DB_TYPES_FAILED).
+ * keeps Docker out of the suite. Before generation, `migration list --local` must prove that the database's applied versions
+ * equal the migration filename stamps (HFS_EMIT_DB_TYPES_STALE otherwise). Unreadable history or failed generation throws HFS_EMIT_DB_TYPES_FAILED.
  */
 import { createHash } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
@@ -44,12 +45,12 @@ const DB_TYPES_SLOT = 'app.supabase.types';
 const CONFIG_FILE = 'supabase/config.toml';
 const SUPABASE_CLI = 'supabase';
 
-/** A types emit that could not run: the code modules/kernel/failure-codes.yaml catalogues as HFS_EMIT_DB_TYPES_FAILED. */
+/** A types emit refuses unreadable history or failed generation with HFS_EMIT_DB_TYPES_FAILED, and unequal applied versions with HFS_EMIT_DB_TYPES_STALE. */
 class DbTypesError extends Error {
-  constructor(message, details = {}) {
-    super(`HFS_EMIT_DB_TYPES_FAILED: ${message}`);
+  constructor(message, details = {}, code = 'HFS_EMIT_DB_TYPES_FAILED') {
+    super(`${code}: ${message}`);
     this.name = 'DbTypesError';
-    this.code = 'HFS_EMIT_DB_TYPES_FAILED';
+    this.code = code;
     this.details = details;
   }
 }
@@ -97,6 +98,97 @@ function apiSchemas(root) {
   return (toml?.api?.schemas ?? []).filter((schema) => typeof schema === 'string');
 }
 
+/** CLI JSON and table rows use the remote field for the database history even with --local; local only describes files. */
+function historyVersion(value) {
+  if (value == null || value === '') return null;
+  if (typeof value !== 'string' || !/^\d+$/.test(value)) {
+    throw new DbTypesError('the local migration history contains an unreadable row', { file: dbTypesPath });
+  }
+  return value;
+}
+
+/** JSON must explicitly carry a migrations array; an empty array proves an empty database history. */
+function jsonAppliedVersions(text) {
+  let history;
+  try { history = JSON.parse(text); } catch {
+    throw new DbTypesError('the local migration history contains unreadable JSON', { file: dbTypesPath });
+  }
+  if (!Array.isArray(history?.migrations)) {
+    throw new DbTypesError('the local migration history has no migrations array', { file: dbTypesPath });
+  }
+  const versions = new Set();
+  for (const row of history.migrations) {
+    if (!row || !Object.hasOwn(row, 'local') || !Object.hasOwn(row, 'remote')) {
+      throw new DbTypesError('the local migration history contains an unreadable row', { file: dbTypesPath });
+    }
+    historyVersion(row.local);
+    const applied = historyVersion(row.remote);
+    if (applied) versions.add(applied);
+  }
+  return versions;
+}
+
+/** Optional outer borders do not add columns; pretty output may wrap each table cell in Markdown backticks. */
+const historyCells = (line, bordered) => {
+  const row = bordered ? line.trim().replace(/^\|/, '').replace(/\|$/, '') : line;
+  return row.split('|').map((cell) => cell.trim().replace(/^`(.*)`$/, '$1'));
+};
+
+/** A recognized header, including a header without rows, proves a table history; malformed rows still refuse. */
+function tableAppliedVersions(lines, header) {
+  const versions = new Set();
+  const bordered = /^\s*\|/.test(lines[header]);
+  const width = historyCells(lines[header], bordered).length;
+  for (const line of lines.slice(header + 1)) {
+    if (/^[\s|+-]+$/.test(line)) continue;
+    if (!line.includes('|')) continue;
+    const cells = historyCells(line, bordered);
+    if (cells.length !== width) {
+      throw new DbTypesError('the local migration history contains an unreadable row', { file: dbTypesPath });
+    }
+    historyVersion(cells[0]);
+    const applied = historyVersion(cells[1]);
+    if (applied) versions.add(applied);
+  }
+  return versions;
+}
+
+/** Read either CLI stream, stripping terminal colors, and require an explicit JSON history or Local | Remote [| Time] header. */
+function appliedVersions(result) {
+  for (const output of [result.stdout, result.stderr]) {
+    const text = String(output ?? '').replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').replaceAll('\u2502', '|').trim();
+    const lines = text.split(/\r?\n/);
+    const json = lines.findIndex((line) => line.trimStart().startsWith('{'));
+    if (json >= 0) return jsonAppliedVersions(lines.slice(json).join('\n'));
+    const header = lines.findIndex((line) => /^\s*\|?\s*Local\s*\|\s*Remote\s*(?:\|\s*Time(?:\s*\(UTC\))?\s*)?\|?\s*$/i.test(line));
+    if (header >= 0) return tableAppliedVersions(lines, header);
+  }
+  throw new DbTypesError('the local migration history is unreadable; expected migrations JSON or the Local | Remote migration list', { file: dbTypesPath });
+}
+
+/** Every applied local version must equal a migration filename stamp, including gaps and extra versions even when the heads match. */
+function requireCurrentDatabase(root, run) {
+  const dir = path.join(root, MIGRATIONS_DIR);
+  const expected = new Set();
+  for (const name of (fs.existsSync(dir) ? fs.readdirSync(dir) : []).filter((file) => file.endsWith('.sql'))) {
+    const stamp = /^(\d+)(?:_|\.sql$)/.exec(name)?.[1];
+    if (!stamp) throw new DbTypesError(`${MIGRATIONS_DIR} contains a SQL file without a migration version`, { file: dbTypesPath });
+    expected.add(stamp);
+  }
+  let result;
+  try { result = run(SUPABASE_CLI, ['migration', 'list', '--local'], { cwd: root }); } catch {
+    throw new DbTypesError('supabase migration list --local could not run; the local migration history must be readable before emitting types', { file: dbTypesPath });
+  }
+  if (result?.error || result?.signal || result?.status !== 0) {
+    throw new DbTypesError('supabase migration list --local failed; the local migration history must be readable before emitting types', { file: dbTypesPath });
+  }
+  const applied = appliedVersions(result);
+  if (applied.size !== expected.size || [...expected].some((version) => !applied.has(version))) {
+    const head = (versions) => [...versions].sort().at(-1) ?? 'none';
+    throw new DbTypesError(`the local database is at ${head(applied)}, the migrations folder at ${head(expected)}; run "npm run db:reset" then emit again`, { file: dbTypesPath }, 'HFS_EMIT_DB_TYPES_STALE');
+  }
+}
+
 /**
  * The freshly generated text of `dbTypesPath` for the app at `root`: `supabase gen types typescript --local` (the running
  * local stack), narrowed to the [api] schemas of supabase/config.toml. A failing CLI, a spawn error and an empty answer all
@@ -104,6 +196,7 @@ function apiSchemas(root) {
  */
 function emitDbTypesWithRunner({ root, run }) {
   const schemas = apiSchemas(root);
+  requireCurrentDatabase(root, run);
   const args = ['gen', 'types', 'typescript', '--local', ...(schemas.length ? ['--schema', schemas.join(',')] : [])];
   const command = `${SUPABASE_CLI} ${args.join(' ')}`;
   let result;

package/lint/run.mjs

@@ -1,6 +1,6 @@
 // starci app lint - the ONE lint entry and the ONE report of a StarCi app.
 //
-//   starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--fix] [--format text|json] [--sonar <file>]
+//   starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--side be|fe] [--fix] [--format text|json] [--sonar <file>]
 //
 // It runs at the app root (the folder of hfs.json), over the app (or over the app-relative files named by --changed):
 //   1. ESLint once per side, from the side folder, through the app's own install and that side's eslint.config.mjs (be/ the be canon,
@@ -26,6 +26,7 @@ import { STYLE_GLOB } from '../sync/index.mjs';
 import { byCodeUnit } from '../report/order.mjs';
 import { braceVariants, globExpression } from '../runtime/scripts/lib/glob.mjs';
 
+// --side judges only that side; root HFS findings belong to be, and Sonar always requires the full lint.
 export const LINT_SCHEMA = 'starci/lint@1';
 /** The side whose stylesheets stylelint judges. */
 const STYLE_SIDE = 'fe';
@@ -41,6 +42,22 @@ export function workspaceOf(workspace) {
   return rel;
 }
 
+/** Side scopes partition the full lint; Sonar requires the complete report and a frontend workspace cannot belong to be. */
+function validateSide(opts) {
+  if (opts.side === undefined) return;
+  if (!SIDES.includes(opts.side)) throw new Error('LINT_SIDE_INVALID: --side is be or fe');
+  if (opts.sonar !== undefined) throw new Error('LINT_SIDE_SONAR_CONFLICT: --side and --sonar do not combine');
+  if (opts.side === 'be' && opts.workspace !== undefined) throw new Error('LINT_SIDE_WORKSPACE_CONFLICT: --side be cannot judge a frontend workspace');
+}
+
+/** Side findings stay with their side; findings outside both sides belong to the backend lint. */
+function findingOnSide(finding, side) {
+  if (side === undefined) return true;
+  const file = posix(finding.path ?? '');
+  const owner = SIDES.find((candidate) => file === candidate || file.startsWith(`${candidate}/`));
+  return (owner ?? 'be') === side;
+}
+
 /** The flags of `starci app lint`; `--changed` takes every argument up to the next flag, and a repeated `--changed` adds to the list (the
  *  catalog's list flag, `--changed a --changed b`, as the CLI dispatcher passes it through). */
 export function parseLintArgs(argv) {
@@ -52,13 +69,15 @@ export function parseLintArgs(argv) {
       while (i + 1 < argv.length && !argv[i + 1].startsWith('--')) opts.changed.push(posix(argv[++i]));
     } else if (arg === '--fix') opts.fix = true;
     else if (arg === '--json') opts.format = 'json';
-    else if (['--format', '--sonar', '--workspace'].includes(arg)) {
+    else if (['--format', '--sonar', '--workspace', '--side'].includes(arg)) {
+      if (arg === '--side' && (argv[i + 1] === undefined || argv[i + 1].startsWith('--'))) throw new Error('LINT_SIDE_INVALID: --side needs be or fe');
       if (argv[i + 1] === undefined) throw new Error(`${arg} needs a value`);
       opts[arg.slice(2)] = argv[++i];
     } else throw new Error(`unknown argument ${arg}`);
   }
   if (!['text', 'json'].includes(opts.format)) throw new Error('--format is text or json');
   if (opts.workspace !== undefined && opts.changed !== null) throw new Error('--workspace and --changed do not combine: a workspace lint judges the whole workspace');
+  validateSide(opts);
   return opts;
 }
 
@@ -182,7 +201,7 @@ function checkedEslintResults({ results, expected, cwd, scope, changed }) {
 /** Starts the ESLint child of every side that has work and returns one record per side: skipped, a scope error, or the running child. */
 async function launchEslint({ app, repoRoot, opts, changed, existing, workspace, onFe }) {
   const launches = [];
-  for (const side of app ? SIDES : []) {
+  for (const side of app ? SIDES.filter((candidate) => opts.side === undefined || opts.side === candidate) : []) {
     if (workspace !== null && side !== STYLE_SIDE) { launches.push({ side, skipped: `outside --workspace ${workspace}` }); continue; }
     const sources = onSide(existing, side).filter((file) => /\.(?:[cm]?[jt]sx?)$/.test(file));
     if (changed !== null && !sources.length) { launches.push({ side, skipped: 'no changed source file' }); continue; }
@@ -197,6 +216,7 @@ async function launchEslint({ app, repoRoot, opts, changed, existing, workspace,
 
 /** Starts stylelint over the fe stylesheets (the running child), or returns null when no stylesheet is in scope. */
 function launchStylelint({ repoRoot, opts, changed, existing, onFe }) {
+  if (opts.side === 'be') return null;
   const styles = onSide(existing, STYLE_SIDE).filter((file) => file.endsWith('.css'));
   if (changed !== null && !styles.length) return null;
   return runLinter({ cwd: path.join(repoRoot, STYLE_SIDE), pkg: 'stylelint', bin: 'stylelint', args: [...(changed ? styles : [onFe ? `${onFe}/src/**/*.css` : STYLE_GLOB]), '--formatter', 'json', ...(opts.fix ? ['--fix'] : [])] });
@@ -210,6 +230,8 @@ export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles =
   const changed = opts.changed === null ? null : new Set(opts.changed);
   const errors = [];
   let workspace = null;
+  let validSide = true;
+  try { validateSide(opts); } catch (error) { errors.push(String(error?.message ?? error)); validSide = false; }
   if (opts.workspace !== undefined) {
     try { workspace = workspaceOf(opts.workspace); } catch (error) { errors.push(String(error?.message ?? error)); }
   }
@@ -223,7 +245,7 @@ export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles =
   let app = null;
   try { app = readRepoDeclaration(loadSlotManifest(), repoRoot); } catch (error) { errors.push(`starci app lint runs at the app root: ${String(error?.message ?? error)}`); }
   if (app && !app.sides) { errors.push(`${repoRoot} is the ${app.side} side of an app; starci app lint runs at the app root, the folder of hfs.json`); app = null; }
-  if (opts.workspace !== undefined && workspace === null) app = null;
+  if (!validSide || (opts.workspace !== undefined && workspace === null)) app = null;
   if (workspace !== null && !fs.existsSync(path.join(repoRoot, workspace, 'package.json'))) { errors.push(`--workspace ${workspace} holds no package.json; it is not a workspace of this app`); app = null; }
   /** The workspace folder relative to the fe side folder (apps/<app> or packages/<pkg>). */
   const onFe = workspace === null ? null : workspace.slice(STYLE_SIDE.length + 1);
@@ -277,7 +299,7 @@ export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles =
     if (settled.error) errors.push(`starci app check could not run: ${String(settled.error?.message ?? settled.error)}`);
     else checked = settled.value;
   }
-  const repoErrors = checked.findings.filter((finding) => finding.level === 'error');
+  const repoErrors = checked.findings.filter((finding) => finding.level === 'error' && findingOnSide(finding, opts.side));
   // A workspace lint keeps only the app findings inside the workspace; the rest belong to the root lint of the whole app.
   const kept = workspace !== null
     ? repoErrors.filter((finding) => finding.path && inWorkspace(finding.path))
@@ -297,7 +319,7 @@ export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles =
     linterReport('eslint', raw.eslint, { root: repoRoot, sourceRoots, tracked }),
     linterReport('stylelint', raw.stylelint, { root: repoRoot, sourceRoots, tracked }),
   ]);
-  const report = { schema: LINT_SCHEMA, ok: findings.length === 0 && errors.length === 0, repoRoot, changed: changed ? [...changed].sort(byCodeUnit) : null, workspace, counts: { error: findings.length }, engines, errors, findings };
+  const report = { schema: LINT_SCHEMA, ok: findings.length === 0 && errors.length === 0, repoRoot, changed: changed ? [...changed].sort(byCodeUnit) : null, workspace, ...(opts.side === undefined ? {} : { side: opts.side }), counts: { error: findings.length }, engines, errors, findings };
   return { report, sonar, exit: errors.length ? 2 : findings.length ? 1 : 0 };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.4.1",
+  "version": "4.5.1",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",
@@ -21,6 +21,7 @@
     "stack/**",
     "release/**",
     "db/**",
+    "ci/**",
     "lint/**",
     "scaffold/**",
     "report/**",

package/release/ci-red.mjs

@@ -0,0 +1,70 @@
+// ci-red.mjs - the latest completed default-branch CI is a release precondition; unreadable GitHub warns, a red run needs the owner's SHA-bound override.
+import fs from 'node:fs';
+import path from 'node:path';
+import { refusal } from '../stack/errors.mjs';
+
+const FIELDS = 'databaseId,headSha,status,conclusion,url,event,createdAt';
+const SHA = /^[a-f0-9]{40}$/u;
+const RED = new Set(['failure', 'cancelled', 'timed_out', 'startup_failure', 'action_required']);
+
+/** Every process uses the supplied seam; an unavailable executable is an unreadable result. */
+function run(spawn, cwd, command, args) {
+  try { return spawn(command, args, { cwd }); } catch { return { status: null }; }
+}
+
+function runsOf(result) {
+  if (result.error || result.status !== 0) return null;
+  try {
+    const rows = JSON.parse(result.stdout);
+    return Array.isArray(rows) ? rows : null;
+  } catch { return null; }
+}
+
+/** Reads branch runs plus push/tag runs whose commits are reachable from the default branch; the newest completed run decides, even if a newer run is pending. */
+export function latestDefaultBranchCi({ spawn, cwd, defaultBranch = 'main' }) {
+  const args = ['run', 'list', '--workflow', 'ci.yml'];
+  const tail = ['--limit', '20', '--json', FIELDS];
+  const branch = runsOf(run(spawn, cwd, 'gh', [...args, '--branch', defaultBranch, ...tail]));
+  if (!branch) return { state: 'unknown', why: 'gh branch runs unavailable (missing gh, authentication, or unreadable response)' };
+  const pushes = runsOf(run(spawn, cwd, 'gh', [...args, '--event', 'push', ...tail]));
+  if (!pushes) return { state: 'unknown', why: 'gh push runs unavailable (missing gh, authentication, or unreadable response)' };
+  const candidates = branch.filter((row) => row && SHA.test(row.headSha));
+  let ancestryUnknown = false;
+  for (const row of pushes) {
+    if (!row || !SHA.test(row.headSha) || row.event !== 'push') continue;
+    const ancestor = run(spawn, cwd, 'git', ['merge-base', '--is-ancestor', row.headSha, defaultBranch]);
+    if (!ancestor.error && ancestor.status === 0) candidates.push(row);
+    else if (ancestor.error || ancestor.status !== 1) ancestryUnknown = true;
+  }
+  const completed = candidates.filter((row) => row.status === 'completed' && Number.isFinite(Date.parse(row.createdAt)));
+  completed.sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt) || Number(b.databaseId) - Number(a.databaseId));
+  const latest = completed[0];
+  if (!latest) return { state: 'unknown', why: ancestryUnknown ? 'cannot establish push run ancestry on the default branch' : 'no completed CI run on the default branch' };
+  if (latest.conclusion === 'success') return { state: 'green', run: latest };
+  if (RED.has(latest.conclusion)) return { state: 'red', run: latest };
+  return { state: 'unknown', why: 'latest completed CI run has no success or red conclusion', run: latest };
+}
+
+/** Only a complete starci/ci-override@1 record for this exact commit can excuse a red run. */
+function overrideOf(ctx, sha) {
+  const common = run(ctx.spawn, ctx.cwd, 'git', ['rev-parse', '--git-common-dir']);
+  if (common.error || common.status !== 0 || !String(common.stdout ?? '').trim()) return null;
+  const file = path.join(path.resolve(ctx.cwd, String(common.stdout).trim()), 'starci-release', `${sha}.ci-override.json`);
+  try {
+    const record = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (record.schema !== 'starci/ci-override@1' || record.sha !== sha || typeof record.reason !== 'string' || !record.reason.trim() || typeof record.by !== 'string' || !record.by.trim() || typeof record.at !== 'string' || !Number.isFinite(Date.parse(record.at))) return null;
+    return record;
+  } catch { return null; }
+}
+
+/** Warns on unknown CI and refuses red CI unless the owner left a valid override beside the release records. */
+export function requireGreenCi(ctx, ci) {
+  if (ci.state === 'unknown') {
+    ctx.stderr(`RELEASE_CI_UNKNOWN: ${ci.why}\n`);
+    return [];
+  }
+  if (ci.state !== 'red') return [];
+  const record = overrideOf(ctx, ci.run.headSha);
+  if (record) return [`RELEASE_CI_RED overridden by the owner: ${record.reason}`];
+  throw refusal('RELEASE_CI_RED', `CI run ${ci.run.url} for ${ci.run.headSha} concluded ${ci.run.conclusion}; the owner must use starci release ci-override --sha ${ci.run.headSha} --reason <text>`);
+}

package/release/gate.mjs

@@ -1,4 +1,4 @@
-// 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
+// gate.mjs - `starci app release gate`: the honest release gate. It runs the app's own gates on a clean HEAD and when all required gates pass 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.
@@ -7,10 +7,13 @@ 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 { qualityServices } from '../runtime/scripts/hfs/ci-declaration.mjs';
 import { firstLine, lines, tool } from '../stack/context.mjs';
 import { failure, refusal } from '../stack/errors.mjs';
+import { latestDefaultBranchCi, requireGreenCi } from './ci-red.mjs';
 
 export const RELEASE_CODE = 'RELEASE_CONFIG_INVALID';
+const SONAR_UNREACHABLE = 'SONAR_UNREACHABLE';
 
 const FIELDS = new Set(['gates', 'tagPrefix', 'defaultBranch', 'tagMatchesVersion']);
 const GATE_FIELDS = new Set(['name', 'command', 'summary', 'env']);
@@ -35,10 +38,41 @@ const scriptGate = (script) => ({
   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) {
+/** Default gates run app-check, the enabled audit, then every managed script present in the app. */
+function defaultGates(scripts, audit) {
   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)];
+  return [{ name: 'app-check', command: ['npx', 'starci', 'app', 'check'], summary: null, env: {} }, ...(audit ? [audit] : []), ...present.map(scriptGate)];
+}
+
+/** Shared quality settings retain the release reader's audit validation, disabled mode and legacy string host compatibility. */
+function releaseServices(services, options) {
+  const audit = services?.audit ?? {};
+  if (!plain(audit) || (audit.in !== undefined && (!Array.isArray(audit.in) || !audit.in.every((scope) => typeof scope === 'string'))) || (audit.omitDev !== undefined && typeof audit.omitDev !== 'boolean')) throw refusal(RELEASE_CODE, 'services.audit must be a mapping with a string-list in and boolean omitDev');
+  const sonar = services?.sonar;
+  const compatible = typeof sonar?.host === 'string' ? { ...sonar, host: { public: sonar.host } } : sonar;
+  const quality = qualityServices({ services: { ...services, sonar: compatible } }, options);
+  if (audit.mode === 'disabled') quality.audit = null;
+  return quality;
+}
+
+/** The shared audit settings preserve release scope, level and development-dependency selection. */
+function auditGate(audit) {
+  if (!audit || !audit.in.includes('release-gate')) return null;
+  if (!['info', 'low', 'moderate', 'high', 'critical'].includes(audit.level)) throw refusal(RELEASE_CODE, 'services.audit.level must be an npm audit level');
+  return { name: 'audit', command: ['npm', 'audit', ...(audit.omitDev ? ['--omit=dev'] : []), `--audit-level=${audit.level}`], summary: null, env: {} };
+}
+
+/** A requested local Sonar scan uses only the declared host and token variable; the token never enters argv. */
+function sonarGate(services, env) {
+  const configured = services?.sonar;
+  const sonar = configured?.provider === 'sonarcloud' ? { ...configured, host: 'https://sonarcloud.io' } : configured;
+  const tokenName = sonar?.token;
+  if (!sonar?.host || !ENV_KEY.test(tokenName) || !env[tokenName]) throw refusal('RELEASE_SONAR_UNAVAILABLE', 'declare an enabled services.sonar host and set its ci.token environment variable');
+  const command = ['npx', '--yes', '@sonar/scan@4.3.0', `-Dsonar.host.url=${sonar.host}`];
+  const organization = sonar.organization ?? (sonar.organizationVar ? env[sonar.organizationVar] : null);
+  if (organization) command.push(`-Dsonar.organization=${organization}`);
+  if (!command.every((word) => TOKEN.test(word))) throw refusal('RELEASE_SONAR_UNAVAILABLE', 'Sonar host and organization must be plain command arguments');
+  return { name: 'sonar', command, summary: null, env: { SONAR_TOKEN: env[tokenName] }, provider: sonar };
 }
 
 function gateProblems(entry, at, seen) {
@@ -74,7 +108,7 @@ function gatesOf(list, problems) {
 }
 
 /** Judges the optional `release:` block. Absence is fine (defaults). Returns { config } or { problems }. */
-export function normalizeRelease(block, scripts = {}) {
+export function normalizeRelease(block, scripts = {}, services = {}, options = {}) {
   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`);
@@ -84,8 +118,11 @@ export function normalizeRelease(block, scripts = {}) {
   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 };
+  const quality = releaseServices(services, options);
+  const audit = auditGate(quality.audit);
+  const gates = raw.gates === undefined ? defaultGates(scripts, audit) : gatesOf(raw.gates, problems);
+  if (raw.gates !== undefined && audit && !gates.some((gate) => gate.name === 'audit')) gates.push(audit);
+  return problems.length === 0 ? { config: { gates, tagPrefix, defaultBranch, tagMatchesVersion, services: quality } } : { problems };
 }
 
 /* ---- git through the seam */
@@ -174,14 +211,42 @@ export function launch(argv, platform) {
   return [argv[0], argv.slice(1)];
 }
 
+/** Sonar availability is public and bounded; HTTP uses the existing injected fetch seam. */
+async function sonarAvailability(ctx, gate) {
+  const sonar = gate.provider;
+  if (!sonar) return null;
+  let up = false;
+  try {
+    const response = await ctx.fetch(sonar.host.replace(/\/$/u, '') + '/api/system/status', { signal: AbortSignal.timeout(10000) });
+    up = response.ok && (await response.json()).status === 'UP';
+  } catch { up = false; }
+  if (up) return null;
+  const detail = sonar.optional
+    ? `notice: sonar skipped: ${sonar.host} not reachable (services.sonar.optional)`
+    : `${SONAR_UNREACHABLE}: ${sonar.host} did not report UP within ten seconds`;
+  return { skipped: sonar.optional === true, pass: false, detail };
+}
+
+/** Unreachable optional providers remain explicit skipped rows, with a real log and no scan invocation. */
+async function runAvailableGate(ctx, gate, options) {
+  const availability = await sonarAvailability(ctx, gate);
+  if (!availability) return runGate(ctx, gate, options);
+  const log = path.join(options.dir, `${gate.name}.log`);
+  fs.writeFileSync(log, availability.detail + '\n');
+  return { name: gate.name, command: gate.command.join(' '), ...availability, seconds: 0,
+    summary: null, log: path.resolve(log), logSha256: sha256(log), env: Object.keys(gate.env) };
+}
+
 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 ?? ''}`;
+  const output = `${run.stdout ?? ''}${run.stderr ?? ''}`;
+  const text = gate.name === 'sonar' && gate.env.SONAR_TOKEN ? output.replaceAll(gate.env.SONAR_TOKEN, '[REDACTED]') : output;
   fs.writeFileSync(log, text);
   const verdict = judgeVerdict(run, gate, text);
+  if (gate.name === 'sonar' && gate.env.SONAR_TOKEN) verdict.detail = verdict.detail.replaceAll(gate.env.SONAR_TOKEN, '[REDACTED]');
   const seconds = Math.round((ctx.now() - started) / 1000);
   return {
     name: gate.name, command: gate.command.join(' '), pass: verdict.pass, detail: verdict.detail, seconds,
@@ -233,7 +298,7 @@ function inspect(ctx, config, options) {
 }
 
 function planLines(config, facts, dir, recordPath) {
-  const out = [`L4 record      ${recordPath}`, `logs           ${dir}`, '', 'gates (all must pass, in this order):'];
+  const out = [`L4 record      ${recordPath}`, `logs           ${dir}`, '', 'gates (required gates must pass, optional provider outages are skipped, 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}`);
@@ -252,47 +317,53 @@ function assertUnmoved(ctx, head) {
 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.',
+    note: 'Required gates passed on a clean HEAD; optional provider skips are explicit and every entry links its log and 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;
+/** Gates run sequentially because each failure prevents subsequent commands and record creation. */
+async function runAll(ctx, config, options) {
+  fs.mkdirSync(options.dir, { recursive: true });
+  return config.gates.reduce(async (pending, gate) => {
+    const results = await pending;
+    if (results.some((result) => !result.pass && !result.skipped)) return results;
+    return [...results, await runAvailableGate(ctx, gate, options)];
+  }, Promise.resolve([]));
 }
 
-const summaryOf = (result) => `${result.pass ? 'PASS' : 'FAIL'} ${result.name} (${result.detail}, ${result.seconds}s) log ${result.log}`;
+function summaryOf(result) {
+  let status = result.pass ? 'PASS' : 'FAIL';
+  if (result.skipped) status = 'SKIPPED';
+  return `${status} ${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 }.
+ * `starci app release gate`: dry run prints the preconditions, the gate list, the head and the tag; --execute runs every gate and, only if required gates pass,
+ * writes the L4 record and creates the annotated tag. options: { execute, sonar, source, tagPrefix, platform }.
  */
 export async function releaseGate(ctx, config, options = {}) {
+  if (options.sonar) config = { ...config, gates: [...config.gates.filter((gate) => gate.name !== 'sonar'), sonarGate(config.services, ctx.env)] };
+  const ci = latestDefaultBranchCi({ spawn: ctx.spawn, cwd: ctx.cwd, defaultBranch: config.defaultBranch });
+  const ciLines = requireGreenCi(ctx, ci);
   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) };
+  const plan = [...ciLines, ...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), ci: { state: ci.state, notices: ciLines } };
   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 results = await runAll(ctx, config, { dir, platform: options.platform ?? process.platform });
   const report = results.map(summaryOf);
-  const failed = results.filter((result) => !result.pass);
+  const failed = results.filter((result) => !result.pass && !result.skipped);
   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]);
+  if (created) git(ctx, ['tag', '-a', facts.chosen.tag, '-m', `release ${facts.chosen.tag}: required gates passed 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

@@ -1,12 +1,13 @@
 // 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 gate [--execute] [--sonar] [--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 { isRuntimeExampleApp } from '../runtime/scripts/lib/runtime-example.mjs';
 import { STACKS_DIR, STACKS_FILE } from '../stack/config.mjs';
 import { stackContext } from '../stack/context.mjs';
 import { EXIT, StackError, refusal } from '../stack/errors.mjs';
@@ -56,7 +57,8 @@ function readPackage(root) {
 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);
+  const declaration = readDeclaration(root);
+  const { config, problems } = normalizeRelease(declaration.release, pkg.scripts, declaration.services, { example: isRuntimeExampleApp(root) });
   if (!config) throw refusal(RELEASE_CODE, `${problems.length} problem(s) in release: ${problems.slice(0, 6).join('; ')}`);
   return { root, version: pkg.version, ...config };
 }
@@ -83,8 +85,8 @@ export async function runVerb({ label, name, io, argv, spec, run, code = 'RELEAS
 
 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'] }),
+    spec: { boolean: ['--execute', '--json', '--sonar'], value: ['--source', '--tag-prefix'] },
+    run: (ctx, flags) => releaseGate(ctx, loadReleaseConfig(ctx.cwd), { execute: flags.execute === true, sonar: flags.sonar === true, source: flags.source, tagPrefix: flags['tag-prefix'] }),
   },
   push: {
     spec: { boolean: ['--execute', '--json'], value: ['--remote'] },

package/release/push.mjs

@@ -14,7 +14,7 @@ function readRecord(file) {
 }
 
 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 || (gate?.name === 'sonar' && gate?.skipped === 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) {

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -29,14 +29,14 @@ pins:
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.4.1
+    version: 3.4.3
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 8.4.1
+    version: 8.4.3
     group: starci
     install: registry
     side: fe
@@ -62,7 +62,7 @@ pins:
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.3.0
+    version: 2.3.1
     group: starci
     install: registry
     side: be
@@ -76,14 +76,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.4.1
+    version: 1.5.1
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
     why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.4.1
+    version: 4.5.1
     group: starci
     install: registry
     side: both