@starci/hfs 4.4.0 → 4.5.0

package/db/reset.mjs

@@ -0,0 +1,125 @@
+// reset.mjs - linked reset requires explicit custody choices, a recent verified encrypted backup and the migration arming rule.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { runVerb } from '../release/index.mjs';
+import { requireArmed } from './migrate.mjs';
+import { failure, refusal } from '../stack/errors.mjs';
+import { backupSession, backupArgs, backupRecipients, backupTool, encryptFile, queryRows, validateReceipt, runCli } from './backup-receipt.mjs';
+
+/** Metadata fingerprints allow verification without printing or retaining rows, object keys or auth identities in the result. */
+function inventory(session, schema) {
+  const tables = queryRows(session, `select tablename from pg_catalog.pg_tables where schemaname = '${schema}' and tablename not in ('schema_migrations', 'migrations') order by tablename;`);
+  return tables.map(({ tablename }) => {
+    if (typeof tablename !== 'string' || !/^[a-z_][a-z0-9_]*$/u.test(tablename)) throw failure('DB_RESET_VERIFY_FAILED', 'invalid preservation table inventory');
+    const rows = queryRows(session, `begin read only; select count(*)::text as count, md5(coalesce(string_agg(md5(row_to_json(t)::text), '' order by md5(row_to_json(t)::text)), '')) as hash from "${schema}"."${tablename}" t; commit;`);
+    if (rows.length !== 1 || !/^\d+$/u.test(String(rows[0].count)) || !/^[a-f0-9]{32}$/u.test(rows[0].hash ?? '')) throw failure('DB_RESET_VERIFY_FAILED', 'invalid preservation fingerprint');
+    return { table: tablename, count: String(rows[0].count), hash: rows[0].hash };
+  });
+}
+
+/** age reads identity bytes on stdin or the configured identity file; neither identity nor SQL is placed in argv or diagnostics. */
+function decryptPart(ctx, encrypted, plaintext) {
+  const key = ctx.env.SOPS_AGE_KEY;
+  const identity = key ? '-' : ctx.env.SOPS_AGE_KEY_FILE;
+  if (!identity) throw refusal('DB_RESET_IDENTITY_MISSING', '--auth/--storage keep needs SOPS_AGE_KEY or SOPS_AGE_KEY_FILE to restore the temporary encrypted part');
+  backupTool(ctx, 'age', ['--decrypt', '--identity', identity, '-o', plaintext, encrypted], key ? { input: `${key}\n` } : {});
+}
+
+function preservePart(session, scratch, schema, recipients) {
+  const before = inventory(session, schema);
+  const plain = path.join(scratch, `${schema}.sql`);
+  const encrypted = `${plain}.age`;
+  runCli(session, ['db', 'dump', '--data-only', '--schema', schema, '--exclude', `${schema}.schema_migrations,${schema}.migrations`, '--file', plain, ...backupArgs(session)]);
+  encryptFile(session.ctx, plain, encrypted, recipients);
+  fs.rmSync(plain, { force: true });
+  // Prove the selected identity can restore this exact part before the destructive call.
+  decryptPart(session.ctx, encrypted, plain);
+  fs.rmSync(plain, { force: true });
+  return { schema, before, encrypted, plain };
+}
+
+function restorePart(session, part) {
+  // Supabase retains some managed tables. Replace their data to avoid duplicate users, buckets or migration-independent metadata.
+  decryptPart(session.ctx, part.encrypted, part.plain);
+  const tables = part.before.map((row) => `"${part.schema}"."${row.table}"`);
+  const source = fs.readFileSync(part.plain, 'utf8');
+  fs.writeFileSync(part.plain, `begin;\nset constraints all deferred;\n${tables.length ? `truncate ${tables.join(', ')} cascade;\n` : ''}${source}\ncommit;\n`, { mode: 0o600 });
+  try { runCli(session, ['db', 'query', '--file', part.plain, '--output', 'json', '--agent', 'no', ...backupArgs(session)]); }
+  finally { fs.rmSync(part.plain, { force: true }); }
+  if (JSON.stringify(inventory(session, part.schema)) !== JSON.stringify(part.before)) throw failure('DB_RESET_VERIFY_FAILED', `${part.schema} data differs after restore; use the full backup receipt for recovery`);
+}
+
+function expectedHead(session) {
+  const dir = path.join(session.ctx.cwd, session.database.migrationsDir ?? 'supabase/migrations');
+  let expected;
+  try { expected = fs.readdirSync(dir).filter((name) => /^\d{14}_[A-Za-z0-9_-]+\.sql$/u.test(name)).map((name) => name.slice(0, 14)).sort(); }
+  catch { throw refusal('DB_MIGRATIONS_MISSING', 'migration directory is not readable'); }
+  if (!expected.length || new Set(expected).size !== expected.length) throw refusal('DB_MIGRATIONS_MISSING', 'migration versions must be present and unique');
+  return expected;
+}
+
+function verifyHead(session) {
+  const expected = expectedHead(session);
+  const actual = queryRows(session, 'select version from supabase_migrations.schema_migrations order by version;').map((row) => row.version);
+  if (JSON.stringify(expected) !== JSON.stringify(actual)) throw failure('DB_RESET_HEAD_MISMATCH', 'reset migration history differs from repository migration versions');
+  return expected;
+}
+
+/** Dry run validates custody and prints a plan; execute preserves chosen managed data, resets, restores and verifies the exact migration head. */
+function resetDatabase(ctx, options = {}) {
+  if (options.linked !== true || options.local || options.urlEnv !== undefined) throw refusal('DB_RESET_LINKED_REQUIRED', 'reset requires --linked; use npm run db:reset for a local database');
+  if (!['keep', 'drop'].includes(options.auth) || !['keep', 'drop'].includes(options.storage)) throw refusal('DB_RESET_CHOICE_MISSING', 'explicit --auth keep|drop and --storage keep|drop are required');
+  const session = backupSession(ctx, options);
+  const receipt = validateReceipt(session, options.backup ? path.resolve(ctx.cwd, options.backup) : undefined);
+  const lines = [`target: linked project ${session.target.ref}`, `backup: verified encrypted receipt from ${receipt.at}`,
+    options.auth === 'keep' ? 'auth: encrypt all auth data tables before reset, restore in a transaction and verify' : 'auth: users and identities are deleted',
+    options.storage === 'keep' ? 'storage: preserve and verify buckets and objects metadata' : 'storage: empty storage.objects metadata; files in the storage backend are not deleted by SQL',
+    'reset: supabase db reset --linked; verify migration versions against repository'];
+  if (!options.execute) return { ok: true, lines: [...lines, 'dry run: nothing changed'], data: { executed: false, auth: options.auth, storage: options.storage, ref: session.target.ref } };
+  requireArmed(ctx);
+  // Refuse unsupported CLI file execution before resetting: SQL containing identity data must never travel in argv.
+  if (options.auth === 'keep' || options.storage === 'keep') {
+    const help = runCli(session, ['db', 'query', '--help']).text;
+    if (!help.includes('--file')) throw refusal('DB_RESET_QUERY_FILE_UNSUPPORTED', 'the Supabase CLI must support db query --file for transactional restore');
+  }
+  expectedHead(session);
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'starci-db-reset-'));
+  const parts = [];
+  let resetStarted = false;
+  let complete = false;
+  try {
+    const keep = ['auth', 'storage'].filter((schema) => options[schema] === 'keep');
+    const recipients = keep.length ? backupRecipients(ctx.cwd) : [];
+    for (const schema of keep) parts.push(preservePart(session, scratch, schema, recipients));
+    resetStarted = true;
+    runCli(session, ['db', 'reset', '--yes', ...backupArgs(session)]);
+    for (const part of parts) restorePart(session, part);
+    if (options.auth === 'drop') {
+      const rows = queryRows(session, 'select (select count(*) from auth.users)::text as users, (select count(*) from auth.identities)::text as identities;');
+      if (rows.length !== 1 || String(rows[0].users) !== '0' || String(rows[0].identities) !== '0') throw failure('DB_RESET_VERIFY_FAILED', 'auth users or identities remain after reset');
+    }
+    if (options.storage === 'drop') {
+      runCli(session, ['db', 'query', 'begin; delete from storage.objects; commit;', '--output', 'json', '--agent', 'no', ...backupArgs(session)]);
+      const rows = queryRows(session, 'select count(*)::text as count from storage.objects;');
+      if (rows.length !== 1 || String(rows[0].count) !== '0') throw failure('DB_RESET_VERIFY_FAILED', 'storage.objects metadata was not emptied');
+    }
+    const versions = verifyHead(session);
+    complete = true;
+    return { ok: true, lines: [...lines, 'reset completed; managed data choices and migration head verified'], data: { executed: true, auth: options.auth, storage: options.storage, ref: session.target.ref, versions } };
+  } finally {
+    // Preserve encrypted recovery parts after a reset/restore failure; remove every plaintext file on every exit.
+    for (const name of fs.readdirSync(scratch)) if (!name.endsWith('.age')) fs.rmSync(path.join(scratch, name), { force: true });
+    if (complete || !resetStarted) fs.rmSync(scratch, { recursive: true, force: true });
+    else ctx.stderr(`DB_RESET_RECOVERY_PARTS: encrypted recovery parts retained at ${scratch}\n`);
+  }
+}
+
+export function dbResetMain(argv, io = {}) {
+  return runVerb({ label: 'starci app db reset', name: 'db reset', code: 'DB_USAGE', io, argv,
+    spec: { boolean: ['--linked', '--execute', '--json', '--local'], value: ['--auth', '--storage', '--backup', '--url-env'] },
+    run: (ctx, flags, positional) => {
+      if (positional.length) throw refusal('DB_USAGE', 'reset takes flags only');
+      return resetDatabase(ctx, { linked: flags.linked, local: flags.local, urlEnv: flags['url-env'], execute: flags.execute, auth: flags.auth, storage: flags.storage, backup: flags.backup });
+    } });
+}

package/emit/contracts.mjs

@@ -41,7 +41,7 @@ const OPERATIONS_WORKER = path.join(path.dirname(fileURLToPath(import.meta.url))
 export const appModulePath = (app) => `apps/${app}/src/app.module.ts`;
 
 /** The repository-relative path of an app's snapshot. */
-export const snapshotPath = (app) => `contracts/${app}/schema.graphql`;
+const snapshotPath = (app) => `contracts/${app}/schema.graphql`;
 
 /** The `paths` aliases of a tsconfig as [{ prefix, targets }], `@modules/*` giving prefix `@modules/`. Pure. */
 export function aliasesOf(paths, baseDir) {
@@ -57,7 +57,7 @@ export function aliasTarget(aliases, specifier) {
 }
 
 /** The api apps of a declaration that can serve GraphQL: kind `api`. Pure. */
-export const apiApps = (declaration) => (declaration.apps ?? []).filter((app) => app.kind === 'api').map((app) => app.name);
+const apiApps = (declaration) => (declaration.apps ?? []).filter((app) => app.kind === 'api').map((app) => app.name);
 
 /** The text written to a snapshot file: the printed schema and one final newline. Pure. */
 export const snapshotText = (printed) => `${printed.replace(/\n+$/, '')}\n`;

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';
@@ -22,13 +23,13 @@ export const dbTypesPath = 'supabase/types/database.types.ts';
 
 /** The folder of the app's migrations, and the first line of the committed types: the digest of the migrations they were generated from. */
 const MIGRATIONS_DIR = 'supabase/migrations';
-export const TYPES_STAMP = '// migrations-sha256: ';
+const TYPES_STAMP = '// migrations-sha256: ';
 
 /**
  * The sha256 of the app's migrations, hex: every `supabase/migrations/*.sql` by name, each as name, NUL, its text with LF line ends,
  * NUL. The offline codegen hook of a lite app (templates/app/codegen-lite) computes the same digest and refuses types stamped with another.
  */
-export function migrationsDigest(root) {
+function migrationsDigest(root) {
   const dir = path.join(root, MIGRATIONS_DIR);
   const hash = createHash('sha256');
   for (const name of (fs.existsSync(dir) ? fs.readdirSync(dir) : []).filter((file) => file.endsWith('.sql')).sort()) {
@@ -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,19 +69,21 @@ 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;
 }
 
 /** The typed ESLint run reads nothing above the app root: its TypeScript `sys` is bound by this preload (3.3, bound-sys.cjs). */
-export const BOUND_ENV = 'STARCI_LINT_BOUND';
-export const linterBoundArgs = () => ['--require', fileURLToPath(new URL('./bound-sys.cjs', import.meta.url))];
+const BOUND_ENV = 'STARCI_LINT_BOUND';
+const linterBoundArgs = () => ['--require', fileURLToPath(new URL('./bound-sys.cjs', import.meta.url))];
 
 /** The child `node` ran with `args` from `cwd`: its exit status, signal, spawn error and the text of both streams, once it closes. */
 function runNode(args, options) {
@@ -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.0",
+  "version": "4.5.0",
   "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

@@ -7,8 +7,10 @@ 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';
 
@@ -35,10 +37,40 @@ 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. */
-export 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 sonar = services?.sonar;
+  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] } };
 }
 
 function gateProblems(entry, at, seen) {
@@ -74,7 +106,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 +116,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 */
@@ -128,7 +163,7 @@ function nextFree(prefix, version, taken) {
 }
 
 /** The tag this release uses and its state: on-head (reused), free (will be created) or taken (exists on another commit). */
-export function chooseTag(ctx, config, { prefix, remote }) {
+function chooseTag(ctx, config, { prefix, remote }) {
   const onHead = annotatedOnHead(ctx, prefix);
   const taken = takenTags(ctx, prefix, remote);
   const exact = `${prefix}${config.version}`;
@@ -147,7 +182,7 @@ const lineAfter = (text, label) => {
 };
 
 /** The jest summary lines of a log: { suites, failedSuites, tests, failed, passed } or null when jest printed none. */
-export function jestSummary(text) {
+function jestSummary(text) {
   const suites = lineAfter(text, 'Test Suites:');
   const tests = lineAfter(text, 'Tests:');
   if (suites === null || tests === null) return null;
@@ -159,7 +194,7 @@ export function jestSummary(text) {
 }
 
 /** Judges a jest-style gate from its log: green needs suites that all passed, every test passed and no coverage threshold miss. */
-export function judgeJest(text) {
+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 };
@@ -179,9 +214,11 @@ function runGate(ctx, gate, { dir, platform }) {
   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,
@@ -274,15 +311,18 @@ const summaryOf = (result) => `${result.pass ? 'PASS' : 'FAIL'} ${result.name} (
 
 /**
  * `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 }.
+ * 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 });