@starci/hfs 4.11.21 → 4.12.0

package/ci/local.mjs

@@ -1,4 +1,4 @@
-// local.mjs - `starci app ci local [--jobs <id,...>] [--parallel <n>] [--dry-run] [--json]`: predict the CI result while GitHub runs it. It reads the app's
+// local.mjs - `starci app ci local [--jobs <id,...>] [--parallel <n>] [--execute] [--json]`: predict the CI result while GitHub runs it. Without --execute it prints the plan (each job instance, its steps run or skipped) and runs nothing. It reads the app's
 // managed .github/workflows/ci.yml (the CI standard's jobs: fast, lint per side, test per shard, coverage, build) and runs the `run:` steps of every job
 // instance on this machine, matrix values substituted, independent instances in parallel and a job after the jobs it `needs`:
 //   - steps GitHub alone can run are skipped and listed: `uses:` actions (checkout, caches, artifacts, Codecov, Sonar), the install (`npm ci`: the local
@@ -13,136 +13,173 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { parseYaml } from '../runtime/engine/yaml.mjs';
-
 const DEFAULT_JOBS = ['fast', 'lint', 'test', 'coverage', 'build'];
 const GITHUB_ONLY_IF = /SONAR_TOKEN\s*!=\s*''|refs\/tags|startsWith\(github\.ref|steps\.|hashFiles|github\.event/;
 const LOCAL_IF = /^(?:\$\{\{\s*)?(?:always\(\)|!cancelled\(\)|env\.SONAR_TOKEN\s*==\s*'')(?:\s*\}\})?$/;
-
+/** The flags of `starci app ci local`; any other argument is refused. */
+export const LOCAL_FLAGS = Object.freeze({ boolean: ['--execute', '--json'], value: ['--jobs', '--parallel', '--logs'] });
 function parseArgs(argv) {
-  const opts = { logs: null, jobs: null, parallel: Math.max(1, Math.min(4, Math.floor(os.cpus().length / 2))), dryRun: false, json: false };
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index];
-    if (arg === '--dry-run') opts.dryRun = true;
-    else if (arg === '--json') opts.json = true;
-    else if (arg === '--jobs' || arg === '--parallel' || arg === '--logs') {
-      const value = argv[index + 1];
-      if (!value || value.startsWith('--')) throw new Error(`${arg} needs a value`);
-      if (arg === '--logs') opts.logs = value;
-      else if (arg === '--jobs') opts.jobs = value.split(',').map((job) => job.trim()).filter(Boolean);
-      else if (!/^[1-9]\d*$/.test(value)) throw new Error('--parallel takes a positive integer');
-      else opts.parallel = Number(value);
-      index += 1;
-    } else throw new Error(`unknown argument ${arg}`);
-  }
-  return opts;
+    const opts = { logs: null, jobs: null, parallel: Math.max(1, Math.min(4, Math.floor(os.cpus().length / 2))), execute: false, json: false };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--execute')
+            opts.execute = true;
+        else if (arg === '--json')
+            opts.json = true;
+        else if (LOCAL_FLAGS.value.includes(arg)) {
+            const value = argv[index + 1];
+            if (!value || value.startsWith('--'))
+                throw new Error(`${arg} needs a value`);
+            if (arg === '--logs')
+                opts.logs = value;
+            else if (arg === '--jobs')
+                opts.jobs = value.split(',').map((job) => job.trim()).filter(Boolean);
+            else if (!/^[1-9]\d*$/.test(value))
+                throw new Error('--parallel takes a positive integer');
+            else
+                opts.parallel = Number(value);
+            index += 1;
+        }
+        else
+            throw new Error(`unknown argument ${arg}`);
+    }
+    return opts;
 }
-
 /** Every combination of a one-level matrix ({side: [be, fe]} -> [{side: be}, {side: fe}]); [{}] without one. */
 function combinations(matrix) {
-  const keys = Object.keys(matrix ?? {}).filter((key) => Array.isArray(matrix[key]));
-  return keys.reduce((all, key) => all.flatMap((partial) => matrix[key].map((value) => ({ ...partial, [key]: value }))), [{}]);
+    const keys = Object.keys(matrix ?? {}).filter((key) => Array.isArray(matrix[key]));
+    return keys.reduce((all, key) => all.flatMap((partial) => matrix[key].map((value) => ({ ...partial, [key]: value }))), [{}]);
 }
-
 const substitute = (text, values) => String(text).replace(/\$\{\{\s*matrix\.([A-Za-z0-9_-]+)\s*\}\}/g, (whole, key) => (Object.hasOwn(values, key) ? String(values[key]) : whole));
-
 /** The local verdict of one step: {run: command} or {skip: why}. */
 function stepPlan(step, values) {
-  const name = step.name ?? (step.uses ? String(step.uses).split('@')[0] : String(step.run ?? '').split('\n')[0].slice(0, 60));
-  if (step.uses) return { name, skip: 'a GitHub action' };
-  const condition = step.if === undefined ? null : String(step.if).trim();
-  if (condition !== null && (GITHUB_ONLY_IF.test(condition) || !LOCAL_IF.test(condition))) return { name, skip: `if: ${condition} needs GitHub context` };
-  let command = substitute(step.run ?? '', values);
-  if (/^npm ci\b/.test(command.trim())) return { name, skip: 'the install: the local node_modules is used' };
-  if (command.includes('$GITHUB_ENV') || command.includes('GITHUB_OUTPUT')) return { name, skip: 'writes GitHub step state' };
-  if (/\$\{\{/.test(command)) return { name, skip: 'needs a GitHub expression' };
-  if (name === 'unit' && values.shard !== undefined) command = `${command} --coverageDirectory coverage/shards/shard-${values.shard}`;
-  const env = Object.fromEntries(Object.entries(step.env ?? {}).filter(([, value]) => !String(value).includes('${{')).map(([key, value]) => [key, substitute(value, values)]));
-  return { name, run: command, env, cwd: step['working-directory'] ? substitute(step['working-directory'], values) : '.' };
+    const name = step.name ?? (step.uses ? String(step.uses).split('@')[0] : String(step.run ?? '').split('\n')[0].slice(0, 60));
+    if (step.uses)
+        return { name, skip: 'a GitHub action' };
+    const condition = step.if === undefined ? null : String(step.if).trim();
+    if (condition !== null && (GITHUB_ONLY_IF.test(condition) || !LOCAL_IF.test(condition)))
+        return { name, skip: `if: ${condition} needs GitHub context` };
+    let command = substitute(step.run ?? '', values);
+    if (/^npm ci\b/.test(command.trim()))
+        return { name, skip: 'the install: the local node_modules is used' };
+    if (command.includes('$GITHUB_ENV') || command.includes('GITHUB_OUTPUT'))
+        return { name, skip: 'writes GitHub step state' };
+    if (/\$\{\{/.test(command))
+        return { name, skip: 'needs a GitHub expression' };
+    if (name === 'unit' && values.shard !== undefined)
+        command = `${command} --coverageDirectory coverage/shards/shard-${values.shard}`;
+    const env = Object.fromEntries(Object.entries(step.env ?? {}).filter(([, value]) => !String(value).includes('${{')).map(([key, value]) => [key, substitute(value, values)]));
+    return { name, run: command, env, cwd: step['working-directory'] ? substitute(step['working-directory'], values) : '.' };
 }
-
 /** The plan of the workflow: [{id, label, needs, steps: [{name, run|skip}]}], one entry per job instance. */
 function localPlan(workflow, jobs = null) {
-  const wanted = jobs ?? DEFAULT_JOBS;
-  const plan = [];
-  for (const [id, job] of Object.entries(workflow?.jobs ?? {})) {
-    if (!wanted.includes(id)) continue;
-    const needs = [job.needs ?? []].flat().map(String).filter((need) => wanted.includes(need));
-    for (const values of combinations(job.strategy?.matrix)) {
-      const suffix = Object.values(values).join('-');
-      plan.push({ id, label: suffix ? `${id}-${suffix}` : id, needs, steps: (job.steps ?? []).map((step) => stepPlan(step, values)) });
+    const wanted = jobs ?? DEFAULT_JOBS;
+    const plan = [];
+    for (const [id, job] of Object.entries(workflow?.jobs ?? {})) {
+        if (!wanted.includes(id))
+            continue;
+        const needs = [job.needs ?? []].flat().map(String).filter((need) => wanted.includes(need));
+        for (const values of combinations(job.strategy?.matrix)) {
+            const suffix = Object.values(values).join('-');
+            plan.push({ id, label: suffix ? `${id}-${suffix}` : id, needs, steps: (job.steps ?? []).map((step) => stepPlan(step, values)) });
+        }
     }
-  }
-  return plan;
+    return plan;
 }
-
 function runStep(step, { root, env, log }) {
-  return new Promise((resolve) => {
-    fs.appendFileSync(log, `\n$ ${step.run}\n`);
-    const child = spawn('bash', ['-c', step.run], { cwd: path.resolve(root, step.cwd), env: { ...env, ...step.env }, windowsHide: true });
-    child.stdout.on('data', (chunk) => fs.appendFileSync(log, chunk));
-    child.stderr.on('data', (chunk) => fs.appendFileSync(log, chunk));
-    child.on('error', (error) => { fs.appendFileSync(log, `\n${error.message}\n`); resolve(1); });
-    child.on('close', (code) => resolve(code ?? 1));
-  });
+    return new Promise((resolve) => {
+        fs.appendFileSync(log, `\n$ ${step.run}\n`);
+        const child = spawn('bash', ['-c', step.run], { cwd: path.resolve(root, step.cwd), env: { ...env, ...step.env }, windowsHide: true });
+        child.stdout.on('data', (chunk) => fs.appendFileSync(log, chunk));
+        child.stderr.on('data', (chunk) => fs.appendFileSync(log, chunk));
+        child.on('error', (error) => { fs.appendFileSync(log, `\n${error.message}\n`); resolve(1); });
+        child.on('close', (code) => resolve(code ?? 1));
+    });
 }
-
 async function runInstance(instance, { root, env, logs }) {
-  const log = path.join(logs, `${instance.label}.log`);
-  fs.writeFileSync(log, `starci app ci local: ${instance.label}\n`);
-  const started = Date.now();
-  for (const step of instance.steps.filter((entry) => entry.run !== undefined)) {
-    const code = await runStep(step, { root, env, log });
-    if (code !== 0) return { label: instance.label, ok: false, failed: step.name, seconds: Math.round((Date.now() - started) / 1000), log };
-  }
-  return { label: instance.label, ok: true, seconds: Math.round((Date.now() - started) / 1000), log };
+    const log = path.join(logs, `${instance.label}.log`);
+    fs.writeFileSync(log, `starci app ci local: ${instance.label}\n`);
+    const started = Date.now();
+    for (const step of instance.steps.filter((entry) => entry.run !== undefined)) {
+        const code = await runStep(step, { root, env, log });
+        if (code !== 0)
+            return { label: instance.label, ok: false, failed: step.name, seconds: Math.round((Date.now() - started) / 1000), log };
+    }
+    return { label: instance.label, ok: true, seconds: Math.round((Date.now() - started) / 1000), log };
 }
-
 /** Run the plan: instances whose needs are all done, `parallel` at a time; an instance whose need failed is not run. */
 async function runPlan(plan, { parallel, root, env, logs, report }) {
-  const results = new Map();
-  const pending = [...plan];
-  const running = new Set();
-  const doneJob = (id) => plan.filter((entry) => entry.id === id).every((entry) => results.has(entry.label));
-  const jobOk = (id) => plan.filter((entry) => entry.id === id).every((entry) => results.get(entry.label)?.ok);
-  await new Promise((resolve) => {
-    const pump = () => {
-      for (const instance of [...pending]) {
-        if (running.size >= parallel) break;
-        if (!instance.needs.every(doneJob)) continue;
-        pending.splice(pending.indexOf(instance), 1);
-        if (!instance.needs.every(jobOk)) { results.set(instance.label, { label: instance.label, ok: false, failed: `needs ${instance.needs.join(', ')}`, seconds: 0 }); continue; }
-        const task = runInstance(instance, { root, env, logs }).then((result) => { results.set(instance.label, result); report(result); running.delete(task); pump(); });
-        running.add(task);
-      }
-      if (!pending.length && !running.size) resolve();
-      else if (!running.size && pending.length) { for (const instance of pending.splice(0)) results.set(instance.label, { label: instance.label, ok: false, failed: 'its needs never completed', seconds: 0 }); resolve(); }
-    };
-    pump();
-  });
-  return plan.map((instance) => results.get(instance.label));
+    const results = new Map();
+    const pending = [...plan];
+    const running = new Set();
+    const doneJob = (id) => plan.filter((entry) => entry.id === id).every((entry) => results.has(entry.label));
+    const jobOk = (id) => plan.filter((entry) => entry.id === id).every((entry) => results.get(entry.label)?.ok);
+    await new Promise((resolve) => {
+        const pump = () => {
+            for (const instance of [...pending]) {
+                if (running.size >= parallel)
+                    break;
+                if (!instance.needs.every(doneJob))
+                    continue;
+                pending.splice(pending.indexOf(instance), 1);
+                if (!instance.needs.every(jobOk)) {
+                    results.set(instance.label, { label: instance.label, ok: false, failed: `needs ${instance.needs.join(', ')}`, seconds: 0 });
+                    continue;
+                }
+                const task = runInstance(instance, { root, env, logs }).then((result) => { results.set(instance.label, result); report(result); running.delete(task); pump(); });
+                running.add(task);
+            }
+            if (!pending.length && !running.size)
+                resolve();
+            else if (!running.size && pending.length) {
+                for (const instance of pending.splice(0))
+                    results.set(instance.label, { label: instance.label, ok: false, failed: 'its needs never completed', seconds: 0 });
+                resolve();
+            }
+        };
+        pump();
+    });
+    return plan.map((instance) => results.get(instance.label));
 }
-
 /** `starci app ci local`. */
 export async function ciLocalMain(argv, { cwd = process.cwd(), stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), env = process.env } = {}) {
-  let opts;
-  try { opts = parseArgs(argv); } catch (error) { stderr(`starci app ci local: ${error.message}; usage: starci app ci local [--jobs <id,...>] [--parallel <n>] [--logs <dir>] [--dry-run] [--json]\n`); return 2; }
-  const file = path.join(cwd, '.github', 'workflows', 'ci.yml');
-  if (!fs.existsSync(file)) { stderr('starci app ci local: no .github/workflows/ci.yml (run starci app sync --write)\n'); return 2; }
-  const plan = localPlan(parseYaml(fs.readFileSync(file, 'utf8')), opts.jobs);
-  if (!plan.length) { stderr('starci app ci local: no job of the workflow is selected\n'); return 2; }
-  if (opts.dryRun) {
-    if (opts.json) stdout(`${JSON.stringify(plan)}\n`);
-    else for (const instance of plan) stdout(`${instance.label}${instance.needs.length ? ` (after ${instance.needs.join(', ')})` : ''}\n${instance.steps.map((step) => `  ${step.run !== undefined ? 'run ' : 'skip'} ${step.name}${step.skip ? ` - ${step.skip}` : ''}`).join('\n')}\n`);
-    return 0;
-  }
-  const logs = opts.logs ? path.resolve(cwd, opts.logs) : fs.mkdtempSync(path.join(os.tmpdir(), 'starci-ci-local-'));
-  fs.mkdirSync(logs, { recursive: true });
-  const defaultBranch = 'main';
-  const runEnv = { ...env, CI: 'true', STARCI_BASE_REF: env.STARCI_BASE_REF ?? `origin/${defaultBranch}`, SONAR_TOKEN: '' };
-  stdout(`starci app ci local: ${plan.length} job instance(s), ${opts.parallel} at a time; logs in ${logs}\n`);
-  const results = await runPlan(plan, { parallel: opts.parallel, root: cwd, env: runEnv, logs, report: (result) => { if (!opts.json) stdout(`${result.ok ? 'green' : 'RED  '} ${result.label} (${result.seconds}s)${result.ok ? '' : ` at ${result.failed}: ${result.log}`}\n`); } });
-  const red = results.filter((result) => !result.ok);
-  if (opts.json) stdout(`${JSON.stringify({ ok: red.length === 0, results, logs })}\n`);
-  else stdout(red.length ? `starci app ci local: ${red.length} of ${results.length} red: ${red.map((result) => result.label).join(', ')}\n` : `starci app ci local: all ${results.length} green\n`);
-  return red.length ? 1 : 0;
+    let opts;
+    try {
+        opts = parseArgs(argv);
+    }
+    catch (error) {
+        stderr(`starci app ci local: ${error.message}; usage: starci app ci local [--jobs <id,...>] [--parallel <n>] [--logs <dir>] [--execute] [--json]\n`);
+        return 2;
+    }
+    const file = path.join(cwd, '.github', 'workflows', 'ci.yml');
+    if (!fs.existsSync(file)) {
+        stderr('starci app ci local: no .github/workflows/ci.yml (run starci app sync --execute)\n');
+        return 2;
+    }
+    const plan = localPlan(parseYaml(fs.readFileSync(file, 'utf8')), opts.jobs);
+    if (!plan.length) {
+        stderr('starci app ci local: no job of the workflow is selected\n');
+        return 2;
+    }
+    if (!opts.execute) {
+        if (opts.json)
+            stdout(`${JSON.stringify(plan)}\n`);
+        else
+            for (const instance of plan)
+                stdout(`${instance.label}${instance.needs.length ? ` (after ${instance.needs.join(', ')})` : ''}\n${instance.steps.map((step) => `  ${step.run !== undefined ? 'run ' : 'skip'} ${step.name}${step.skip ? ` - ${step.skip}` : ''}`).join('\n')}\n`);
+        return 0;
+    }
+    const logs = opts.logs ? path.resolve(cwd, opts.logs) : fs.mkdtempSync(path.join(os.tmpdir(), 'starci-ci-local-'));
+    fs.mkdirSync(logs, { recursive: true });
+    const defaultBranch = 'main';
+    const runEnv = { ...env, CI: 'true', STARCI_BASE_REF: env.STARCI_BASE_REF ?? `origin/${defaultBranch}`, SONAR_TOKEN: '' };
+    stdout(`starci app ci local: ${plan.length} job instance(s), ${opts.parallel} at a time; logs in ${logs}\n`);
+    const results = await runPlan(plan, { parallel: opts.parallel, root: cwd, env: runEnv, logs, report: (result) => { if (!opts.json)
+            stdout(`${result.ok ? 'green' : 'RED  '} ${result.label} (${result.seconds}s)${result.ok ? '' : ` at ${result.failed}: ${result.log}`}\n`); } });
+    const red = results.filter((result) => !result.ok);
+    if (opts.json)
+        stdout(`${JSON.stringify({ ok: red.length === 0, results, logs })}\n`);
+    else
+        stdout(red.length ? `starci app ci local: ${red.length} of ${results.length} red: ${red.map((result) => result.label).join(', ')}\n` : `starci app ci local: all ${results.length} green\n`);
+    return red.length ? 1 : 0;
 }

package/ci/secret.d.mts

@@ -0,0 +1,15 @@
+import type { CiDeclaration, CiEntry, CiOptions, Gh, StdinSource } from './github.mjs';
+/** A declared name must belong to the requested store before a secret body is read. */
+export declare function declaredEntry(entries: readonly CiEntry[], name: string, options: CiOptions): CiEntry;
+/** Secret input is read once, stripped of one trailing newline, and passed only to the child stdin; without options.execute nothing is read or written. */
+export declare function setSecret({ declaration, sealed, gh, options, name, stdin, stdout }: {
+    declaration: CiDeclaration;
+    sealed: readonly {
+        key: string;
+    }[];
+    gh: Gh;
+    options: CiOptions;
+    name: string;
+    stdin: StdinSource;
+    stdout: (text: string) => unknown;
+}): Promise<number>;

package/ci/secret.mjs

@@ -1,28 +1,38 @@
 import fs from 'node:fs';
 import { refuse, scopeArgs, scopeName } from './github.mjs';
-
 /** A declared name must belong to the requested store before a secret body is read. */
 export function declaredEntry(entries, name, options) {
-  const entry = entries.find((item) => item.name === name);
-  if (!entry) throw refuse('CI_NAME_UNDECLARED', 'the name is not declared for this CI class');
-  const environment = entry.scope === 'environment' ? entry.environment : undefined;
-  if (environment !== options.env || (options.dependabot && options.env)) throw refuse('CI_SCOPE_MISMATCH', 'the requested scope differs from the declaration');
-  return entry;
+    const entry = entries.find((item) => item.name === name);
+    if (!entry)
+        throw refuse('CI_NAME_UNDECLARED', 'the name is not declared for this CI class');
+    const environment = entry.scope === 'environment' ? entry.environment : undefined;
+    if (environment !== options.env || (options.dependabot && options.env))
+        throw refuse('CI_SCOPE_MISMATCH', 'the requested scope differs from the declaration');
+    return entry;
 }
-
-/** Secret input is read once, stripped of one trailing newline, and passed only to the child stdin. */
+/** Secret input is read once, stripped of one trailing newline, and passed only to the child stdin; without options.execute nothing is read or written. */
 export async function setSecret({ declaration, sealed, gh, options, name, stdin, stdout }) {
-  if (sealed.some((item) => item.key === name)) throw refuse('CI_SECRET_SEALED', 'the name belongs to a sealed app secret');
-  declaredEntry(options.dependabot ? declaration.dependabotSecrets : declaration.secrets, name, options);
-  let value;
-  if (stdin === undefined) {
-    if (process.stdin.isTTY) throw refuse('CI_VALUE_EMPTY', 'a secret value is required on stdin');
-    value = fs.readFileSync(0, 'utf8');
-  } else value = typeof stdin === 'function' ? await stdin() : stdin;
-  value = String(value ?? '').replace(/\r?\n$/, '');
-  if (!value.length) throw refuse('CI_VALUE_EMPTY', 'a secret value is required on stdin');
-  const repo = gh.repository(options.repo);
-  gh.run(['secret', 'set', name, ...scopeArgs(options), '--repo', repo], value);
-  stdout(`set secret ${name} (${scopeName(options)})\n`);
-  return 0;
+    if (sealed.some((item) => item.key === name))
+        throw refuse('CI_SECRET_SEALED', 'the name belongs to a sealed app secret');
+    declaredEntry(options.dependabot ? declaration.dependabotSecrets : declaration.secrets, name, options);
+    // Dry until --execute: the name is judged, but no value is read and GitHub is not reached; the line never carries a value.
+    if (options.execute !== true) {
+        stdout(`dry run: would set secret ${name} (${scopeName(options)}) from the value on stdin; add --execute\n`);
+        return 0;
+    }
+    let value;
+    if (stdin === undefined) {
+        if (process.stdin.isTTY)
+            throw refuse('CI_VALUE_EMPTY', 'a secret value is required on stdin');
+        value = fs.readFileSync(0, 'utf8');
+    }
+    else
+        value = typeof stdin === 'function' ? await stdin() : stdin;
+    value = String(value ?? '').replace(/\r?\n$/, '');
+    if (!value.length)
+        throw refuse('CI_VALUE_EMPTY', 'a secret value is required on stdin');
+    const repo = gh.repository(options.repo);
+    gh.run(['secret', 'set', name, ...scopeArgs(options), '--repo', repo], value);
+    stdout(`set secret ${name} (${scopeName(options)})\n`);
+    return 0;
 }

package/ci/vars.d.mts

@@ -0,0 +1,17 @@
+import type { CiDeclaration, CiOptions, Gh, StdinSource } from './github.mjs';
+/** Owner-supplied variables accept stdin only; other public variables retain manifest and argv agreement. */
+export declare function setVariable({ declaration, gh, options, name, stdin, stdout }: {
+    declaration: CiDeclaration;
+    gh: Gh;
+    options: CiOptions;
+    name: string;
+    stdin: StdinSource;
+    stdout: (text: string) => unknown;
+}): Promise<number>;
+/** Sync validates the whole plan first and performs no GitHub access until execution is requested. */
+export declare function syncVariables({ declaration, gh, options, stdout }: {
+    declaration: CiDeclaration;
+    gh: Gh;
+    options: CiOptions;
+    stdout: (text: string) => unknown;
+}): number;

package/ci/vars.mjs

@@ -1,50 +1,64 @@
 import fs from 'node:fs';
 import { refuse, scopeArgs, scopeName } from './github.mjs';
 import { declaredEntry } from './secret.mjs';
-
 /** Public CI values may come from argv or the manifest, but two supplied values must agree. */
 function valueOf(entry, supplied) {
-  const declared = entry.value === undefined ? undefined : String(entry.value);
-  if (supplied !== undefined && declared !== undefined && supplied !== declared) throw refuse('CI_VAR_DRIFT', 'the supplied value differs from the manifest');
-  const value = supplied ?? declared;
-  if (value === undefined) throw refuse('CI_VALUE_EMPTY', 'a public variable value is required');
-  return value;
+    const declared = entry.value === undefined ? undefined : String(entry.value);
+    if (supplied !== undefined && declared !== undefined && supplied !== declared)
+        throw refuse('CI_VAR_DRIFT', 'the supplied value differs from the manifest');
+    const value = supplied ?? declared;
+    if (value === undefined)
+        throw refuse('CI_VALUE_EMPTY', 'a public variable value is required');
+    return value;
 }
-
 function writeVariable(gh, repo, entry, value, options, stdout) {
-  gh.run(['variable', 'set', entry.name, '--body', value, ...scopeArgs(options), '--repo', repo]);
-  stdout(`set variable ${entry.name} (${scopeName(options)})\n`);
+    gh.run(['variable', 'set', entry.name, '--body', value, ...scopeArgs(options), '--repo', repo]);
+    stdout(`set variable ${entry.name} (${scopeName(options)})\n`);
 }
-
 /** Owner-supplied input is read once from stdin, with one trailing newline removed and no value echoed. */
 async function ownerValueOf(options, stdin) {
-  if (Object.hasOwn(options, 'value')) throw refuse('CI_VALUE_ARGV', 'an owner-supplied variable takes its value on stdin');
-  let value;
-  if (stdin === undefined) {
-    if (process.stdin.isTTY) throw refuse('CI_VALUE_EMPTY', 'an owner-supplied variable value is required on stdin');
-    value = fs.readFileSync(0, 'utf8');
-  } else value = typeof stdin === 'function' ? await stdin() : stdin;
-  value = String(value ?? '').replace(/\r?\n$/, '');
-  if (!value.length) throw refuse('CI_VALUE_EMPTY', 'an owner-supplied variable value is required on stdin');
-  return value;
+    if (Object.hasOwn(options, 'value'))
+        throw refuse('CI_VALUE_ARGV', 'an owner-supplied variable takes its value on stdin');
+    let value;
+    if (stdin === undefined) {
+        if (process.stdin.isTTY)
+            throw refuse('CI_VALUE_EMPTY', 'an owner-supplied variable value is required on stdin');
+        value = fs.readFileSync(0, 'utf8');
+    }
+    else
+        value = typeof stdin === 'function' ? await stdin() : stdin;
+    const text = String(value ?? '').replace(/\r?\n$/, '');
+    if (!text.length)
+        throw refuse('CI_VALUE_EMPTY', 'an owner-supplied variable value is required on stdin');
+    return text;
 }
-
 /** Owner-supplied variables accept stdin only; other public variables retain manifest and argv agreement. */
 export async function setVariable({ declaration, gh, options, name, stdin, stdout }) {
-  const entry = declaredEntry(declaration.vars, name, options);
-  const value = entry.ownerValue ? await ownerValueOf(options, stdin) : valueOf(entry, options.value);
-  writeVariable(gh, gh.repository(options.repo), entry, value, options, stdout);
-  return 0;
+    const entry = declaredEntry(declaration.vars, name, options);
+    // Dry until --execute: the declaration and the supplied value are judged, but nothing is read from stdin and GitHub is not reached.
+    if (options.execute !== true) {
+        if (entry.ownerValue && Object.hasOwn(options, 'value'))
+            throw refuse('CI_VALUE_ARGV', 'an owner-supplied variable takes its value on stdin');
+        if (!entry.ownerValue)
+            valueOf(entry, options.value);
+        stdout(`dry run: would set variable ${entry.name} (${scopeName(options)})${entry.ownerValue ? ' from the value on stdin' : ''}; add --execute\n`);
+        return 0;
+    }
+    const value = entry.ownerValue ? await ownerValueOf(options, stdin) : valueOf(entry, options.value);
+    writeVariable(gh, gh.repository(options.repo), entry, value, options, stdout);
+    return 0;
 }
-
 /** Sync validates the whole plan first and performs no GitHub access until execution is requested. */
 export function syncVariables({ declaration, gh, options, stdout }) {
-  const plan = declaration.vars.map((entry) => ({ entry, value: entry.ownerValue ? undefined : valueOf(entry), options: { env: entry.scope === 'environment' ? entry.environment : undefined } }));
-  const repo = options.execute && plan.some((item) => !item.entry.ownerValue) ? gh.repository(options.repo) : undefined;
-  for (const item of plan) {
-    if (item.entry.ownerValue) stdout(`skip variable ${item.entry.name} (${scopeName(item.options)}): owner-supplied value; the owner runs starci app ci var set ${item.entry.name} [--env ENV] with the value on stdin\n`);
-    else if (options.execute) writeVariable(gh, repo, item.entry, item.value, item.options, stdout);
-    else stdout(`would set variable ${item.entry.name} (${scopeName(item.options)})\n`);
-  }
-  return 0;
+    const plan = declaration.vars.map((entry) => ({ entry, value: entry.ownerValue ? undefined : valueOf(entry), options: { env: entry.scope === 'environment' ? entry.environment : undefined } }));
+    const repo = options.execute && plan.some((item) => !item.entry.ownerValue) ? gh.repository(options.repo) : undefined;
+    for (const item of plan) {
+        if (item.entry.ownerValue)
+            stdout(`skip variable ${item.entry.name} (${scopeName(item.options)}): owner-supplied value; the owner runs starci app ci var set ${item.entry.name} [--env ENV] --execute with the value on stdin\n`);
+        else if (options.execute)
+            writeVariable(gh, repo, item.entry, item.value, item.options, stdout);
+        else
+            stdout(`would set variable ${item.entry.name} (${scopeName(item.options)})\n`);
+    }
+    return 0;
 }

package/ci/verify.d.mts

@@ -0,0 +1,18 @@
+import type { CiDeclaration, CiOptions, Gh } from './github.mjs';
+/** Verification reports names and scopes only; values are compared in memory and excluded from findings. */
+export declare function verifyCi({ declaration, sealed, gh, options, stdout, notices }: {
+    declaration: CiDeclaration;
+    sealed: readonly {
+        key: string;
+    }[];
+    gh: Gh;
+    options: CiOptions;
+    stdout: (text: string) => unknown;
+    notices?: string[];
+}): number;
+/** Manifest visibility wins; optional GitHub visibility discovery never changes verification findings or errors. */
+export declare function badgeVisibilityNotices({ doc, gh, repo }: {
+    doc: any;
+    gh: Gh;
+    repo: string;
+}): string[];