@vodmal/vdx-cli 0.29.0 → 0.31.0

package/README.md

@@ -45,6 +45,9 @@ vdx init  [project-path] [--baseline github.com/org/repo@vX.Y] [--stack <id>] [-
 # Publish a library (Node MVP; PHP/Python coming in Y.3)
 vdx publish <patch|minor|major> [--dry-run] [--force] [--no-push]
 
+# Push the branch; one that requires checks on GitHub takes the commit once they pass
+vdx push [project-path] [--dry-run]   # default: cwd
+
 # Environment self-check (Node / git / mise / npm auth / docker / Claude Code plugin; git hooks of the project)
 vdx doctor [project-path] [--format=ansi|markdown|json]   # default: cwd
 vdx doctor --check [project-path]   # one line per hook declared but not running here — the plugin's SessionStart hook tells the agent
@@ -88,6 +91,17 @@ vdx ai
 vdx ai@m3
 ```
 
+`vdx push` pushes the current branch to its upstream. When the upstream is on
+GitHub and requires checks (branch protection or a ruleset), the commit goes to
+`vdx-gate/<branch>` first; CI checks it there — its workflow has to run on
+`vdx-gate/**` — and vdx waits for the checks, then pushes the same commit to the
+branch with its annotated tags. A failed check leaves the branch as it was and
+names the check. Without required checks, or off GitHub, it is a plain
+`git push`. Its pushes through the checks carry `VDX_GATE_PUSH=1`, so a pre-push
+hook that runs what CI runs can step aside. `vdx publish` sends its release
+commit the same way, after `npm publish`, and then refuses local commits not
+pushed yet: npm would get them before CI.
+
 `vdx ai` reads a personal profile, never a bundled one: `$VDX_ENVIRONMENT`, else
 `~/.vdx-environment.yaml`, else a plain `claude`/`codex` with no flags. Format:
 [docs/specs/environment-format.md](../docs/specs/environment-format.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "vdx — unified lifecycle interface (up/down/build/test/check/fix) + versioned maturity audit with drift detection. Pairs with the vdx Claude Code plugin.",
   "keywords": [
     "vdx",

package/src/gate.ts

@@ -0,0 +1,183 @@
+/**
+ * `vdx push`: a commit reaches a branch that requires checks only once they pass
+ * (DL #8–#10 of docs/tasks/hosting-extension). It goes to a gate branch of its own,
+ * CI checks it there, and the branch takes the same commit — the same SHA, a linear
+ * history. A branch that requires nothing, a remote not on GitHub, a hosting that
+ * does not answer: a plain `git push`, as before.
+ */
+import { execFileSync } from 'node:child_process';
+import { commitChecks, githubRepo, machineIo, requiredChecks, type CheckState, type HostingIo } from './hosting.ts';
+import { errorMessage } from './narrow.ts';
+import type { Unknown } from './predicates.ts';
+
+/** The branch CI checks a commit on before `<branch>` takes it: `vdx-gate/main`. */
+export const GATE_PREFIX = 'vdx-gate/';
+/** Set for the pushes `vdx push` makes: a pre-push hook that runs what CI runs may step aside. */
+const GATE_ENV = 'VDX_GATE_PUSH';
+
+/** Where a push goes, and through what. */
+export interface GateTarget {
+  remote: string;
+  branch: string;
+  repo: string;
+  token: string | null;
+  /** What the branch requires — GitHub's names. */
+  checks: string[];
+}
+
+export type GatePlan =
+  | { kind: 'gate'; target: GateTarget }
+  /** Nothing to wait for: `git push` as it is. */
+  | { kind: 'plain'; why: string }
+  | { kind: 'refuse'; message: string };
+
+function isUnknown(v: object): v is Unknown {
+  return 'unknown' in v;
+}
+
+/** The current branch, its upstream and what the upstream requires — nothing is fetched. */
+export function planGate(io: HostingIo): GatePlan {
+  const local = io.git(['symbolic-ref', '--quiet', '--short', 'HEAD']);
+  if (!local) return { kind: 'refuse', message: 'HEAD is not on a branch — nothing to push it to' };
+  const remote = io.git(['config', '--get', `branch.${local}.remote`]);
+  const merge = io.git(['config', '--get', `branch.${local}.merge`]);
+  if (!remote || !merge?.startsWith('refs/heads/')) {
+    return { kind: 'refuse', message: `${local} has no upstream — git push -u <remote> ${local}` };
+  }
+  const branch = merge.slice('refs/heads/'.length);
+  const gh = githubRepo(io, remote);
+  if (isUnknown(gh)) return { kind: 'plain', why: gh.unknown };
+  let checks: string[] | Unknown;
+  try {
+    checks = requiredChecks(io, gh.repo, branch, gh.token);
+  } catch (e) {
+    return { kind: 'plain', why: `GitHub did not answer: ${errorMessage(e)}` };
+  }
+  if (isUnknown(checks)) return { kind: 'plain', why: checks.unknown };
+  if (checks.length === 0) return { kind: 'plain', why: `${remote}/${branch} requires no checks` };
+  const behind = parseInt(io.git(['rev-list', '--count', 'HEAD..@{u}']) ?? '0', 10) || 0;
+  if (behind > 0) {
+    return {
+      kind: 'refuse',
+      message: `${remote}/${branch} has ${behind} commit(s) this branch lacks — pull first; CI would check a commit ${branch} cannot take`,
+    };
+  }
+  return { kind: 'gate', target: { remote, branch, repo: gh.repo, token: gh.token, checks } };
+}
+
+/** What a gated push does outside — the machine's own below, a fake in the tests. */
+export interface GateDeps {
+  io: HostingIo;
+  /** `git <args>` with `VDX_GATE_PUSH=1`, its output on this terminal; throws on a non-zero exit. */
+  push: (args: string[]) => void;
+  log: (line: string) => void;
+  /** Rewrites one status line in place (a terminal); without it the wait logs a line now and then. */
+  progress?: (text: string) => void;
+  sleep: (ms: number) => void;
+  now: () => number;
+  /** How often GitHub is asked: its limit is 60 an hour without a token. */
+  pollMs: number;
+  timeoutMs: number;
+}
+
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+export function defaultGateDeps(root: string): GateDeps {
+  return {
+    io: machineIo(root),
+    push: (args) => {
+      execFileSync('git', ['-C', root, ...args], { stdio: 'inherit', env: { ...process.env, [GATE_ENV]: '1' } });
+    },
+    log: (line) => process.stderr.write(line + '\n'),
+    progress: process.stderr.isTTY ? (text) => process.stderr.write(`\r${text}\x1b[K`) : undefined,
+    sleep: sleepSync,
+    now: Date.now,
+    pollMs: 15_000,
+    timeoutMs: 20 * 60_000,
+  };
+}
+
+const passed = (states: CheckState[]) => states.every((s) => s.state === 'passed');
+const brief = (states: CheckState[]) => states.map((s) => `${s.name}: ${s.detail.replace(/_/g, ' ')}`).join(', ');
+
+/**
+ * HEAD to the target branch through its checks: the gate branch, the wait, then the
+ * branch itself, with the annotated tags on the way (`--follow-tags` — a release's
+ * tag). Throws when the branch did not take the commit; the reason names what next.
+ */
+export function pushThroughGate(t: GateTarget, d: GateDeps): void {
+  const sha = d.io.git(['rev-parse', 'HEAD']);
+  if (!sha) throw new Error('git rev-parse HEAD failed');
+  const short = sha.slice(0, 7);
+  const where = `${t.remote}/${t.branch}`;
+  if (d.io.git(['rev-parse', '@{u}']) === sha) {
+    d.log(`✓ ${where} is at ${short} already — nothing to push`);
+    return;
+  }
+  const names = t.checks.join(', ');
+  const link = `https://github.com/${t.repo}/commit/${sha}/checks`;
+  const again = `once they pass: vdx push (${link})`;
+  const ask = () => {
+    try {
+      return commitChecks(d.io, t.repo, sha, t.checks, t.token);
+    } catch (e) {
+      return { unknown: `GitHub did not answer: ${errorMessage(e)}` };
+    }
+  };
+  const toBranch = () => {
+    d.log(`→ git push --follow-tags ${t.remote} ${short}:${t.branch}`);
+    d.push(['push', '--follow-tags', t.remote, `${sha}:refs/heads/${t.branch}`]);
+    d.log(`✓ ${where} is at ${short}`);
+  };
+
+  // Pushed once and checked: the branch takes it now.
+  const before = ask();
+  if (!isUnknown(before) && passed(before)) {
+    d.log(`✓ ${short} has passed ${names}`);
+    toBranch();
+    return;
+  }
+
+  const gate = GATE_PREFIX + t.branch;
+  d.log(`→ git push --force ${t.remote} ${short}:${gate} — ${where} requires ${names}; CI checks the commit there`);
+  d.push(['push', '--force', t.remote, `${sha}:refs/heads/${gate}`]);
+  d.log(`→ waiting for ${names} on ${short} (asking every ${Math.round(d.pollMs / 1000)} s): ${link}`);
+
+  const started = d.now();
+  const seconds = () => Math.round((d.now() - started) / 1000);
+  let lastLogged = 0;
+  let shown = '';
+  for (;;) {
+    // Between the asks, count the seconds on one line: a silent wait looks hung.
+    const next = d.now() + d.pollMs;
+    while (d.now() < next) {
+      if (d.progress) d.progress(`  … ${seconds()} s${shown}`);
+      else if (seconds() - lastLogged >= 30) {
+        lastLogged = seconds();
+        d.log(`  … ${lastLogged} s${shown}`);
+      }
+      d.sleep(1_000);
+    }
+    const states = ask();
+    d.progress?.('');
+    if (isUnknown(states)) throw new Error(`${states.unknown} — ${t.branch} did not take ${short}; ${again}`);
+    const failed = states.filter((s) => s.state === 'failed');
+    if (failed.length > 0) {
+      const which = failed.map((s) => `${s.name} — ${s.detail}${s.url ? ` (${s.url})` : ''}`).join('; ');
+      throw new Error(`${which}: ${t.branch} did not take ${short}`);
+    }
+    if (passed(states)) {
+      d.log(`✓ ${names} passed (${seconds()} s)`);
+      toBranch();
+      return;
+    }
+    if (d.now() - started >= d.timeoutMs) {
+      throw new Error(
+        `${brief(states)} after ${Math.round(d.timeoutMs / 60_000)} min — ${t.branch} did not take ${short}; ${again}`,
+      );
+    }
+    shown = ` — ${brief(states)}`;
+  }
+}

package/src/hooks.ts

@@ -428,12 +428,30 @@ export function unsetGatingVars(commands: string[], env: NodeJS.ProcessEnv = pro
   for (const body of commands) {
     for (const m of body.matchAll(GATING_VAR_RE)) {
       const name = m[1] ?? m[2];
-      if (name && !env[name]) out.add(name);
+      if (name && !env[name] && !opensAnEscape(body.slice(m.index + m[0].length))) out.add(name);
     }
   }
   return [...out].sort();
 }
 
+/**
+ * `[ -n "$VAR" ] && exit 0`, `if [ -n "$VAR" ]; then echo …; exit 0; fi`: the variable
+ * lets the hook step aside (`VDX_GATE_PUSH` of `vdx push`), and unset, the hook runs in
+ * full — no gate is a no-op. A block doing anything but saying so and exiting 0 is a gate.
+ */
+function opensAnEscape(afterTest: string): boolean {
+  const m = afterTest.match(/^\s*\](?:\s*;?\s*then\b([\s\S]*?)\bfi\b|\s*&&([^\n]*))/);
+  const block = m?.[1] ?? m?.[2];
+  if (block === undefined) return false;
+  const statements = block
+    .split(/\n|;/)
+    .map((st) => st.trim())
+    .filter((st) => st !== '');
+  return (
+    statements.at(-1) === 'exit 0' && statements.every((st) => st === 'exit 0' || /^(?:echo|printf|:)(?:\s|$)/.test(st))
+  );
+}
+
 /**
  * A program a command runs from this machine, outside the repository:
  * `$HOME/…`, `~/…`, `/Users/…` — quoted or bare, at the head of a command.

package/src/hosting.ts

@@ -60,7 +60,7 @@ function get(apiPath: string, token: string | null): Answer {
   return { status, body };
 }
 
-function machineIo(root: string): HostingIo {
+export function machineIo(root: string): HostingIo {
   const run = (cmd: string, args: string[]): string | null => {
     try {
       return (
@@ -152,17 +152,129 @@ export function branchRequiresChecks(ctx: Ctx, io: HostingIo = machineIo(ctx.pro
 }
 
 function ask(io: HostingIo): Verdict {
+  const gh = githubRepo(io, 'origin');
+  if (isUnknownRepo(gh)) return gh;
+  try {
+    return judge(io, gh.repo, gh.token);
+  } catch (e) {
+    return { unknown: `GitHub did not answer: ${errorMessage(e)}` };
+  }
+}
+
+/** A remote's repository on GitHub and the token to ask with; unknown, with the reason, when vdx cannot ask. */
+export function githubRepo(io: HostingIo, remote: string): { repo: string; token: string | null } | Unknown {
   if (io.env.VDX_OFFLINE) return { unknown: 'VDX_OFFLINE is set — the hosting was not asked' };
-  const url = io.git(['remote', 'get-url', 'origin']);
-  if (!url) return { unknown: 'no origin remote — the hosting is not known' };
+  const url = io.git(['remote', 'get-url', remote]);
+  if (!url) return { unknown: `no ${remote} remote — the hosting is not known` };
   const { host, path: repo } = remoteParts(url);
   // The host only: a URL can carry a token.
   if (host !== 'github.com')
-    return { unknown: `origin is on ${host || 'a host vdx cannot tell'} — vdx reads GitHub only` };
-  const token = io.env.GH_TOKEN || io.env.GITHUB_TOKEN || io.ghToken();
-  try {
-    return judge(io, repo, token);
-  } catch (e) {
-    return { unknown: `GitHub did not answer: ${errorMessage(e)}` };
+    return { unknown: `${remote} is on ${host || 'a host vdx cannot tell'} — vdx reads GitHub only` };
+  return { repo, token: io.env.GH_TOKEN || io.env.GITHUB_TOKEN || io.ghToken() };
+}
+
+function isUnknownRepo(v: { repo: string } | Unknown): v is Unknown {
+  return 'unknown' in v;
+}
+
+/**
+ * The checks a branch requires before it takes a commit — of classic protection and of
+ * rulesets together, whoever they bind: what GitHub will ask of the commit.
+ */
+export function requiredChecks(io: HostingIo, repo: string, branch: string, token: string | null): string[] | Unknown {
+  const ref = encodeURIComponent(branch);
+  const names = new Set<string>();
+  const b = io.get(`/repos/${repo}/branches/${ref}`, token);
+  const refusedBranch = refusal(b, repo, token);
+  if (refusedBranch) return refusedBranch;
+  const classic = at(b.body, 'protection', 'required_status_checks');
+  if (at(classic, 'enforcement_level') !== 'off') {
+    for (const c of list(at(classic, 'checks'))) add(names, at(c, 'context'));
+    for (const c of list(at(classic, 'contexts'))) add(names, c);
+  }
+  const rules = io.get(`/repos/${repo}/rules/branches/${ref}`, token);
+  const refusedRules = refusal(rules, repo, token);
+  if (refusedRules) return refusedRules;
+  for (const rule of list(rules.body)) {
+    if (at(rule, 'type') !== 'required_status_checks') continue;
+    for (const c of list(at(rule, 'parameters', 'required_status_checks'))) add(names, at(c, 'context'));
+  }
+  return [...names];
+}
+
+function add(names: Set<string>, name: unknown): void {
+  const n = str(name);
+  if (n) names.add(n);
+}
+
+/** Where one required check of a commit stands. */
+export interface CheckState {
+  name: string;
+  state: 'pending' | 'passed' | 'failed';
+  /** GitHub's word for it: `in_progress`, `success`, `failure`, `not started`. */
+  detail: string;
+  url?: string;
+}
+
+/**
+ * The named checks of a commit: its check runs (GitHub Actions), else its commit
+ * statuses (an outside CI). A check that has not reported yet is pending.
+ */
+export function commitChecks(
+  io: HostingIo,
+  repo: string,
+  sha: string,
+  names: string[],
+  token: string | null,
+): CheckState[] | Unknown {
+  const runs = io.get(`/repos/${repo}/commits/${sha}/check-runs?per_page=100`, token);
+  const refusedRuns = refusal(runs, repo, token);
+  if (refusedRuns) return refusedRuns;
+  // A re-run is a new check run under the same name: the newest one counts.
+  const latest = new Map<string, unknown>();
+  for (const run of list(at(runs.body, 'check_runs'))) {
+    const name = str(at(run, 'name'));
+    const id = at(run, 'id');
+    if (!name || typeof id !== 'number') continue;
+    const seen = at(latest.get(name), 'id');
+    if (typeof seen !== 'number' || id > seen) latest.set(name, run);
+  }
+  let statuses: Map<string, unknown> | null = null;
+  const states: CheckState[] = [];
+  for (const name of names) {
+    const run = latest.get(name);
+    if (run !== undefined) {
+      const status = str(at(run, 'status')) ?? 'queued';
+      const conclusion = str(at(run, 'conclusion')) ?? '';
+      const url = str(at(run, 'html_url'));
+      const state =
+        status !== 'completed'
+          ? 'pending'
+          : ['success', 'neutral', 'skipped'].includes(conclusion)
+            ? 'passed'
+            : 'failed';
+      states.push({ name, state, detail: status === 'completed' ? conclusion : status, ...(url ? { url } : {}) });
+      continue;
+    }
+    if (statuses === null) {
+      const combined = io.get(`/repos/${repo}/commits/${sha}/status`, token);
+      const refused = refusal(combined, repo, token);
+      if (refused) return refused;
+      statuses = new Map();
+      for (const s of list(at(combined.body, 'statuses'))) {
+        const context = str(at(s, 'context'));
+        if (context && !statuses.has(context)) statuses.set(context, s);
+      }
+    }
+    const status = statuses.get(name);
+    const word = str(at(status, 'state'));
+    const url = str(at(status, 'target_url'));
+    states.push({
+      name,
+      state: word === 'success' ? 'passed' : word === 'failure' || word === 'error' ? 'failed' : 'pending',
+      detail: word ?? 'not started',
+      ...(url ? { url } : {}),
+    });
   }
+  return states;
 }

package/src/index.ts

@@ -34,6 +34,7 @@ import {
   type PublishOptions,
 } from './publish.ts';
 import { resolveDefaultRubric } from './defaults.ts';
+import { defaultGateDeps, GATE_PREFIX, planGate, pushThroughGate } from './gate.ts';
 import { runAi, runAiCheck, runAiRemote, defaultDeps, hostLabel, REMOTE_HOST_RE } from './ai.ts';
 import { isConversationId } from './conversations.ts';
 
@@ -44,6 +45,7 @@ const USAGE = `Usage:
   vdx audit   [project_path]  [--rubric <path>] [--stack <stack>] [--format=ansi|markdown|json] [--json]   (default: cwd)
   vdx init    [project_path]  [--stack <id>] [--baseline <ref>] [--dry-run] [--force]                     (default: cwd)
   vdx publish <patch|minor|major> [--dry-run] [--force] [--no-push]
+  vdx push    [project_path] [--dry-run]                     (default: cwd; through the branch's required checks)
   vdx doctor  [project_path] [--check | --fix] [--format=ansi|markdown|json] [--json]          (default: cwd)
   vdx ai[@host] [project_path] [--new | --conversation <id>] [--restart] [--detach] [--dry-run]   (default: cwd; @host: over ssh, in tmux there)
   vdx <command> --help                   what the command does; an unknown option is refused (exit 2)
@@ -151,7 +153,9 @@ mise.toml is overwritten only with --force.
   the version bump in package.json and package-lock.json;
   npm publish (npm asks for an OTP or a confirmation in the browser; Ctrl-C
   there puts the version back);
-  git commit and tag, then \`git push --follow-tags\` to the branch's upstream;
+  git commit and tag, then \`git push --follow-tags\` to the branch's upstream —
+  through its checks when it requires some, as \`vdx push\` does: the pre-flight
+  then refuses local commits not pushed yet, npm would get them before CI;
   a wait until the registry shows the new version (up to 3 min).
 --dry-run runs the pre-flight and prints the plan; --force goes on past a failed
 pre-flight; --no-push leaves the commit and the tag local.
@@ -159,6 +163,31 @@ pre-flight; --no-push leaves the commit and the tag local.
     bools: ['dry-run', 'force', 'no-push'],
     positionals: 1,
   },
+  push: {
+    usage: 'vdx push [project_path] [--dry-run]',
+    help: `Pushes the current branch to its upstream. When the upstream is on GitHub and
+requires checks (branch protection or a ruleset), the commit goes to
+${GATE_PREFIX}<branch> first: CI checks it there, vdx waits for the checks and then
+pushes the same commit to the branch, with its annotated tags (--follow-tags).
+A failed check leaves the branch as it was and names the check. A branch that
+requires no checks, a remote not on GitHub, a GitHub that does not answer: a
+plain \`git push\`, hooks and all.
+
+The pushes through the checks carry VDX_GATE_PUSH=1: a pre-push hook that runs
+what CI runs may step aside. GitHub is asked with a token from $GH_TOKEN,
+$GITHUB_TOKEN or gh when there is one — without one it answers 60 requests an
+hour, and a push takes about ten; VDX_OFFLINE=1 does not ask.
+
+  project_path  the repository (default: cwd)
+  --dry-run     say which way the push goes; push nothing
+
+Exit codes: 0 pushed; 2 nowhere to push it (no branch, no upstream, behind it);
+3 the branch did not take the commit — a check failed, did not finish in 20 min,
+or GitHub stopped answering; a plain git push exits with git's own code.
+`,
+    bools: ['dry-run'],
+    positionals: 1,
+  },
   doctor: {
     usage: 'vdx doctor [project_path] [--check | --fix] [--format=ansi|markdown|json] [--json]',
     help: `Checks this machine for what vdx needs (Node, git, mise, npm auth, docker, the
@@ -435,6 +464,39 @@ function cmdPublish(opts: ParsedArgs): void {
   }
 }
 
+function cmdPush(opts: ParsedArgs): void {
+  const root = path.resolve(opts.positionals[0] ?? '.');
+  const deps = defaultGateDeps(root);
+  const plan = planGate(deps.io);
+  if (plan.kind === 'refuse') {
+    process.stderr.write(`vdx push: ${plan.message}\n`);
+    process.exit(2);
+  }
+  if (plan.kind === 'plain') {
+    process.stderr.write(`→ git push — ${plan.why}\n`);
+    if (opts.flags['dry-run']) return;
+    try {
+      execFileSync('git', ['-C', root, 'push'], { stdio: 'inherit' });
+    } catch (e) {
+      const status = at(e, 'status');
+      process.exit(typeof status === 'number' ? status : 1);
+    }
+    return;
+  }
+  const t = plan.target;
+  process.stderr.write(
+    `→ ${t.remote}/${t.branch} requires ${t.checks.join(', ')}: through ${GATE_PREFIX}${t.branch}, ` +
+      `then ${t.branch} once they pass\n`,
+  );
+  if (opts.flags['dry-run']) return;
+  try {
+    pushThroughGate(t, deps);
+  } catch (e) {
+    process.stderr.write(`\nerror: ${errorMessage(e)}\n`);
+    process.exit(3);
+  }
+}
+
 function cmdRun(verb: LifecycleVerb): void {
   const projectRoot = process.cwd();
   const res = resolveLifecycleVerb(projectRoot, verb);
@@ -551,6 +613,7 @@ else if (['--help', '-h', 'help'].includes(parsed.cmd)) process.stdout.write(USA
 else if (parsed.cmd === 'audit') cmdAudit(checkArgs('audit', parsed));
 else if (parsed.cmd === 'init') cmdInit(checkArgs('init', parsed));
 else if (parsed.cmd === 'publish') cmdPublish(checkArgs('publish', parsed));
+else if (parsed.cmd === 'push') cmdPush(checkArgs('push', parsed));
 else if (parsed.cmd === 'doctor') cmdDoctor(checkArgs('doctor', parsed));
 else if (parsed.cmd === 'ai' || parsed.cmd.startsWith('ai@')) cmdAi(checkArgs('ai', parsed));
 else if ((LIFECYCLE_VERBS as readonly string[]).includes(parsed.cmd)) {

package/src/publish.ts

@@ -3,6 +3,8 @@ import * as path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import type { AuditResult } from './audit.ts';
 import { stackForDir, type Ctx } from './facts.ts';
+import { defaultGateDeps, GATE_PREFIX, planGate, pushThroughGate, type GatePlan, type GateTarget } from './gate.ts';
+import { machineIo } from './hosting.ts';
 import { at, dict, errorMessage, stderrOf, str } from './narrow.ts';
 
 export type BumpKind = 'patch' | 'minor' | 'major';
@@ -34,6 +36,8 @@ export interface PushPlan {
   ahead: number;
   /** Upstream commits not here: the push would be refused. */
   behind: number;
+  /** The upstream requires checks: the release commit goes through them (`vdx push`). */
+  gate?: GateTarget;
 }
 
 export interface PublishPlan {
@@ -226,6 +230,7 @@ export function planPublish(
   ctx: Ctx,
   npm: NpmRunner = runNpm,
   git: GitRunner = runGit,
+  gate: (projectRoot: string) => GatePlan = (root) => planGate(machineIo(root)),
 ): PublishPlan {
   if (checkMiseOverride(opts.projectRoot)) {
     return {
@@ -339,6 +344,10 @@ export function planPublish(
   }
 
   const push = planPush(opts.projectRoot, opts.push ?? true, git);
+  if (push.enabled && push.upstream) {
+    const g = gate(opts.projectRoot);
+    if (g.kind === 'gate') push.gate = g.target;
+  }
   if (push.enabled && push.upstream && push.behind > 0) {
     preflight.push({
       name: 'push-target',
@@ -347,13 +356,25 @@ export function planPublish(
         `${push.upstream} has ${push.behind} commit(s) this branch lacks — the push after npm publish ` +
         `would be refused. Pull first (or --no-push)`,
     });
+  } else if (push.gate && push.ahead > 0) {
+    // npm publish comes before the push (DL #9 of docs/tasks/hosting-extension): what
+    // CI has not seen would reach npm first.
+    preflight.push({
+      name: 'push-target',
+      ok: false,
+      message:
+        `${push.ahead} local commit(s) are not on ${push.upstream}, which requires ${push.gate.checks.join(', ')}: ` +
+        `npm would get them before CI checks them. Push them first: vdx push`,
+    });
   } else if (push.enabled) {
     preflight.push({
       name: 'push-target',
       ok: true,
-      message: push.upstream
-        ? `OK (${push.upstream}${push.ahead ? `, ${push.ahead} local commit(s) go with the release` : ''})`
-        : 'no upstream for this branch — the release commit and tag stay local',
+      message: push.gate
+        ? `OK (${push.upstream}, through ${push.gate.checks.join(', ')})`
+        : push.upstream
+          ? `OK (${push.upstream}${push.ahead ? `, ${push.ahead} local commit(s) go with the release` : ''})`
+          : 'no upstream for this branch — the release commit and tag stay local',
     });
   }
 
@@ -394,6 +415,8 @@ export interface PublishDeps {
   registryWaitMs: number;
   /** Rewrites one status line in place (a terminal); without it the wait logs a line now and then. */
   progress?: (text: string) => void;
+  /** HEAD through the upstream's checks, with the tag (`vdx push`); throws when the upstream did not take it. */
+  gatePush: (target: GateTarget, projectRoot: string) => void;
 }
 
 function sleepSync(ms: number): void {
@@ -410,6 +433,7 @@ export function defaultPublishDeps(): PublishDeps {
     sleep: sleepSync,
     registryWaitMs: 180_000,
     progress: process.stderr.isTTY ? (text) => process.stderr.write(`\r${text}\x1b[K`) : undefined,
+    gatePush: (target, projectRoot) => pushThroughGate(target, defaultGateDeps(projectRoot)),
   };
 }
 
@@ -480,6 +504,7 @@ export function waitForRegistry(name: string, version: string, deps: PublishDeps
  *      is recoverable manually).
  *   4. `git push --follow-tags` to the branch's upstream, unless `--no-push`
  *      or there is none. The pre-flight refused a branch behind its upstream.
+ *      An upstream that requires checks takes the commit through them (`vdx push`).
  *   5. Wait until the registry shows the version.
  *
  * On npm publish failure or interruption (Ctrl-C at its prompt) → restore the original files.
@@ -541,7 +566,18 @@ export function executePublish(plan: PublishPlan, deps: PublishDeps = defaultPub
 
   // 4. push
   const push = plan.push;
-  if (push?.enabled && push.upstream) {
+  if (push?.enabled && push.gate) {
+    try {
+      deps.gatePush(push.gate, plan.projectRoot);
+    } catch (e) {
+      deps.log(
+        `✗ ${errorMessage(e)} — ${plan.packageName}@${plan.newVersion} is published and tagged here; ` +
+          `once the checks pass: vdx push`,
+      );
+      throw new Error(`${push.upstream} did not take the release commit`, { cause: e });
+    }
+    deps.log(`✓ pushed to ${push.upstream} with tag v${plan.newVersion}, through ${push.gate.checks.join(', ')}`);
+  } else if (push?.enabled && push.upstream) {
     deps.log(`→ git push --follow-tags (${push.upstream})...`);
     try {
       deps.run('git', ['push', '--follow-tags'], plan.projectRoot);
@@ -616,9 +652,11 @@ export function renderPublishPlan(plan: PublishPlan): string {
     lines.push(
       !push?.enabled
         ? '5. Not pushed (`--no-push`): `git push --follow-tags` is yours'
-        : push.upstream
-          ? `5. \`git push --follow-tags\` → ${push.upstream}${push.ahead ? ` (with ${push.ahead} local commit(s) not pushed yet)` : ''}`
-          : '5. Not pushed: the branch has no upstream',
+        : push.gate
+          ? `5. Through CI (\`vdx push\`): \`${GATE_PREFIX}${push.gate.branch}\`, then ${push.upstream} with the tag once ${push.gate.checks.join(', ')} pass`
+          : push.upstream
+            ? `5. \`git push --follow-tags\` → ${push.upstream}${push.ahead ? ` (with ${push.ahead} local commit(s) not pushed yet)` : ''}`
+            : '5. Not pushed: the branch has no upstream',
     );
     lines.push(`6. Wait until the registry shows ${plan.newVersion} (up to 3 min)`);
   } else {