@vodmal/vdx-cli 0.32.1 → 0.34.0

package/README.md

@@ -127,11 +127,25 @@ By default the bundled `rubric/vdx-rubric.yaml` is used (a mirror of canonical
 each CLI release). Override via `--rubric <path>` or the env var `VDX_RUBRIC`.
 
 `branch-protection` is the one axis the files cannot answer: `vdx audit` asks
-GitHub whether the default branch of `origin` takes changes only after a check
-required of everyone, admins included. A public repo needs no token; a private
-one takes it from `GH_TOKEN`, `GITHUB_TOKEN` or `gh auth token`. Another
-hosting, no network or no token where one is needed leave the axis unknown,
-with the reason in the report; `VDX_OFFLINE=1` does not ask at all.
+the hosting of `origin` whether its default branch takes changes only after a
+check required of everyone, admins included. GitHub: protection or a ruleset
+nobody bypasses; a public repo needs no token, a private one takes it from
+`GH_TOKEN`, `GITHUB_TOKEN` or `gh auth token`. GitLab (a host with `gitlab` in
+its name, or one glab has a token for): nobody may push to the branch directly,
+and a merge request needs a passing pipeline; the token is glab's for that
+host, or `GITLAB_TOKEN` when the host is `GITLAB_HOST` (`gitlab.com` unless
+set) — vdx never sends a token to a host it does not belong to. Bitbucket
+Server (a host `BITBUCKET_HOST` names, one with `bitbucket` in its name, or one
+git keeps an https login for — and that says it is Bitbucket): a restriction
+lets nothing into the branch but a pull request and exempts nobody, and a pull
+request needs a successful build ("Minimum successful builds"); the login is
+the one git keeps for that host (`git credential fill`, never a prompt — log in
+once with `git ls-remote https://<host>/scm/<project>/<repo>.git`, a personal
+access token as the password), or `BITBUCKET_TOKEN` when the host is
+`BITBUCKET_HOST`. Branch restrictions are visible to a repository admin only.
+Not met comes with the reason; another hosting, no network or no token
+where one is needed leave the axis unknown, with the reason too;
+`VDX_OFFLINE=1` does not ask at all.
 
 ## Dev
 
@@ -172,8 +186,9 @@ npm run typecheck
 ## Not implemented yet
 
 - Above L1 the `ci` axis reads GitHub Actions only; other CI systems answer
-  "unknown". `branch-protection` is "unknown" everywhere until a hosting
-  extension exists.
+  "unknown". `branch-protection` reads GitHub, GitLab and Bitbucket Server;
+  other hostings (gitolite, Bitbucket Cloud) answer "unknown", and so do
+  Bitbucket restrictions by pattern or branching model.
 - Baseline loading from a git ref is documented but evaluator still reads file
   paths only — `baseline:` in `mise.toml` is recorded but does not auto-fetch.
 - Watermark drift (phase 2 of `drift-algorithm.md`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.32.1",
+  "version": "0.34.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/hosting.ts

@@ -4,7 +4,7 @@ import type { Ctx } from './facts.ts';
 import { at, errorMessage, list, str } from './narrow.ts';
 import type { Unknown, Verdict } from './predicates.ts';
 
-/** One answer of the GitHub API: its status and its body, parsed (null when not JSON). */
+/** One answer of a hosting's API: its status and its body, parsed (null when not JSON). */
 export interface Answer {
   status: number;
   body: unknown;
@@ -17,16 +17,28 @@ export interface HostingIo {
   git: (args: string[]) => string | null;
   /** The token `gh` keeps; null without gh or a login. */
   ghToken: () => string | null;
-  /** GET of an api.github.com path. Throws when no answer came at all. */
-  get: (apiPath: string, token: string | null) => Answer;
+  /** The token `glab` keeps for a GitLab host; null without glab or a login there. */
+  glabToken: (host: string) => string | null;
+  /** The login git keeps for https://<host> (`git credential fill`), never by a prompt; null without one. */
+  gitCredential: (host: string) => { username: string; password: string } | null;
+  /**
+   * GET of an api.github.com path, or of a whole https:// URL, with the token as `Bearer`
+   * or `Basic`. Throws when no answer came at all.
+   */
+  get: (apiPath: string, token: string | null, scheme?: 'Bearer' | 'Basic') => Answer;
 }
 
 // A child node runs the request: the audit is synchronous and fetch is not
 // (DL #6 of docs/tasks/hosting-extension). The token travels in its
-// environment, not its arguments — those are visible in ps.
+// environment, not its arguments — those are visible in ps. GitHub's media
+// type only to GitHub: Bitbucket answers it with 406 (DL #17).
 const GET = `
-const headers = { accept: 'application/vnd.github+json', 'x-github-api-version': '2022-11-28', 'user-agent': 'vdx' };
-if (process.env.VDX_GITHUB_TOKEN) headers.authorization = 'Bearer ' + process.env.VDX_GITHUB_TOKEN;
+const headers = new URL(process.argv[1]).host === 'api.github.com'
+  ? { accept: 'application/vnd.github+json', 'x-github-api-version': '2022-11-28', 'user-agent': 'vdx' }
+  : { accept: 'application/json', 'user-agent': 'vdx' };
+if (process.env.VDX_HOSTING_TOKEN) {
+  headers.authorization = (process.env.VDX_HOSTING_SCHEME || 'Bearer') + ' ' + process.env.VDX_HOSTING_TOKEN;
+}
 try {
   const r = await fetch(process.argv[1], { headers, signal: AbortSignal.timeout(15000) });
   process.stdout.write(JSON.stringify({ status: r.status, text: await r.text() }));
@@ -35,12 +47,14 @@ try {
 }
 `;
 
-function get(apiPath: string, token: string | null): Answer {
+function get(apiPath: string, token: string | null, scheme: 'Bearer' | 'Basic' = 'Bearer'): Answer {
   const env = { ...process.env };
-  delete env.VDX_GITHUB_TOKEN;
-  if (token) env.VDX_GITHUB_TOKEN = token;
+  delete env.VDX_HOSTING_TOKEN;
+  delete env.VDX_HOSTING_SCHEME;
+  if (token) Object.assign(env, { VDX_HOSTING_TOKEN: token, VDX_HOSTING_SCHEME: scheme });
+  const url = apiPath.startsWith('https://') ? apiPath : `https://api.github.com${apiPath}`;
   const out: unknown = JSON.parse(
-    execFileSync(process.execPath, ['--input-type=module', '-e', GET, `https://api.github.com${apiPath}`], {
+    execFileSync(process.execPath, ['--input-type=module', '-e', GET, url], {
       encoding: 'utf8',
       env,
       // node's own start counts too: at a load of ~7 on lft 10 s ran out (2026-10-20).
@@ -76,6 +90,26 @@ export function machineIo(root: string): HostingIo {
     env: process.env,
     git: (args) => run('git', ['--no-optional-locks', '-C', root, ...args]),
     ghToken: () => run('gh', ['auth', 'token']),
+    glabToken: (host) => run('glab', ['config', 'get', 'token', '--host', host]),
+    gitCredential: (host) => {
+      if (!/^[a-z0-9.-]+$/i.test(host)) return null;
+      try {
+        const out = execFileSync('git', ['--no-optional-locks', '-C', root, 'credential', 'fill'], {
+          encoding: 'utf8',
+          input: `protocol=https\nhost=${host}\n\n`,
+          // Without a login git would ask for one: no terminal, no askpass program, no window.
+          env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_ASKPASS: '', GCM_INTERACTIVE: 'never' },
+          stdio: ['pipe', 'pipe', 'ignore'],
+          timeout: 5_000,
+        });
+        const field = (key: string) => out.match(new RegExp(`^${key}=(.*)$`, 'm'))?.[1];
+        const username = field('username');
+        const password = field('password');
+        return username && password ? { username, password } : null;
+      } catch {
+        return null;
+      }
+    },
     get,
   };
 }
@@ -160,7 +194,8 @@ function judge(io: HostingIo, repo: string, token: string | null): Verdict {
 
 /**
  * Whether the default branch on the hosting of `origin` takes changes only after a check
- * required of everyone. GitHub only; what vdx cannot ask is unknown, with the reason.
+ * required of everyone. GitHub, GitLab and Bitbucket Server; what vdx cannot ask is unknown,
+ * with the reason.
  */
 export function branchRequiresChecks(ctx: Ctx, io: HostingIo = machineIo(ctx.projectRoot)): Verdict {
   const key = 'hosting:branch-requires-checks';
@@ -172,12 +207,231 @@ 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)}` };
+  if (!isUnknownRepo(gh)) {
+    try {
+      return judge(io, gh.repo, gh.token);
+    } catch (e) {
+      return { unknown: `GitHub did not answer: ${errorMessage(e)}` };
+    }
+  }
+  if (io.env.VDX_OFFLINE) return gh;
+  const url = io.git(['remote', 'get-url', 'origin']);
+  if (!url) return gh;
+  const { host, path: repo } = remoteParts(url);
+  // GitLab: the host GITLAB_HOST names, one glab has a token for (gitlab.finam.ru, DL #12),
+  // or one with gitlab in its name. A token goes only where it belongs: GITLAB_TOKEN to
+  // GITLAB_HOST, as glab sends it; glab's to its own host. Any other host is asked without
+  // one — an origin is the repository's to name, and may point anywhere.
+  const tokenHost = hostOf(io.env.GITLAB_HOST || 'gitlab.com');
+  const glab = io.glabToken(host);
+  const token = (host.toLowerCase() === tokenHost ? io.env.GITLAB_TOKEN : undefined) || glab;
+  if (host.toLowerCase() === tokenHost || glab || host.includes('gitlab')) {
+    try {
+      return judgeGitlab(io, host, repo, token);
+    } catch (e) {
+      return { unknown: `${host} did not answer: ${errorMessage(e)}` };
+    }
+  }
+  // Bitbucket Server: the host BITBUCKET_HOST names, one with bitbucket in its name, or one
+  // git keeps a login for (git.finam.ru, DL #16) — once the host, asked without a login,
+  // says it is Bitbucket. BITBUCKET_TOKEN goes to BITBUCKET_HOST only, git's login to the
+  // host git keeps it for.
+  const bitbucketHost = io.env.BITBUCKET_HOST ? hostOf(io.env.BITBUCKET_HOST) : null;
+  const login = io.gitCredential(host);
+  if (host.toLowerCase() === bitbucketHost || host.toLowerCase().includes('bitbucket') || login) {
+    const auth: BitbucketAuth | null =
+      host.toLowerCase() === bitbucketHost && io.env.BITBUCKET_TOKEN
+        ? { token: io.env.BITBUCKET_TOKEN, scheme: 'Bearer', source: 'BITBUCKET_TOKEN' }
+        : login
+          ? {
+              token: Buffer.from(`${login.username}:${login.password}`).toString('base64'),
+              scheme: 'Basic',
+              source: 'the login git keeps',
+            }
+          : null;
+    try {
+      const about = io.get(`https://${host}/rest/api/1.0/application-properties`, null);
+      if (about.status === 200 && at(about.body, 'displayName') === 'Bitbucket') {
+        return judgeBitbucket(io, host, repo, auth);
+      }
+    } catch (e) {
+      return { unknown: `${host} did not answer: ${errorMessage(e)}` };
+    }
+  }
+  // Not every host is asked whether it is Bitbucket: gitolite has no https, and the audit
+  // would wait out the timeout. The reason says how vdx tells Bitbucket.
+  return {
+    unknown: `origin is on ${host || 'a host vdx cannot tell'} — vdx reads GitHub, GitLab and Bitbucket Server, the last once git keeps a login for it or BITBUCKET_HOST names it`,
+  };
+}
+
+/** The host of a `*_HOST` variable, which may come as a URL. */
+function hostOf(value: string): string {
+  return value
+    .replace(/^https?:\/\//, '')
+    .replace(/\/.*$/, '')
+    .toLowerCase();
+}
+
+/** A refusal of a GitLab API as the reason the answer is unknown; null for a 200. */
+function gitlabRefusal(a: Answer, host: string, repo: string, token: string | null): Unknown | null {
+  if (a.status === 200) return null;
+  const message = str(at(a.body, 'message')) ?? str(at(a.body, 'error')) ?? '';
+  if (a.status === 429) return { unknown: `${host}'s rate limit is spent` };
+  if ((a.status === 401 || a.status === 404) && !token) {
+    return {
+      unknown: `${host} does not show ${repo} without a token — private? glab auth login --hostname ${host}, or GITLAB_TOKEN`,
+    };
+  }
+  return { unknown: `${host} answered ${a.status} for ${repo}${message ? `: ${message}` : ''}` };
+}
+
+/**
+ * GitLab: the default branch takes changes only after a pipeline when nobody may push to
+ * it directly — a push skips the pipeline — and a merge request needs one that passed
+ * (`only_allow_merge_if_pipeline_succeeds`). The agent pushes as the owner (DL #3).
+ */
+function judgeGitlab(io: HostingIo, host: string, repo: string, token: string | null): Verdict {
+  const base = `https://${host}/api/v4/projects/${encodeURIComponent(repo)}`;
+  const p = io.get(base, token);
+  const refused = gitlabRefusal(p, host, repo, token);
+  if (refused) return refused;
+  const branch =
+    io.git(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'])?.replace(/^origin\//, '') ||
+    str(at(p.body, 'default_branch'));
+  if (!branch) return { unknown: `${host} names no default branch for ${repo}` };
+  const pipeline = at(p.body, 'only_allow_merge_if_pipeline_succeeds') === true;
+
+  const pb = io.get(`${base}/protected_branches/${encodeURIComponent(branch)}`, token);
+  const isProtected = pb.status === 200;
+  if (!isProtected && pb.status !== 404) {
+    const refusedBranch = gitlabRefusal(pb, host, repo, token);
+    if (refusedBranch) return refusedBranch;
+  }
+  // Who may push straight to the branch: a role above "No one" (0), a user, a group, a deploy key.
+  const pushers = list(at(pb.body, 'push_access_levels'))
+    .filter(
+      (l) =>
+        at(l, 'access_level') !== 0 ||
+        at(l, 'user_id') != null ||
+        at(l, 'group_id') != null ||
+        at(l, 'deploy_key_id') != null,
+    )
+    .map((l) => str(at(l, 'access_level_description')) ?? 'someone');
+  if (isProtected && pushers.length === 0 && pipeline) return true;
+
+  const why: string[] = [];
+  if (!isProtected) why.push(`${branch} is not protected`);
+  else if (pushers.length > 0)
+    why.push(`${branch} takes direct pushes from ${pushers.join(', ')} — a push skips the pipeline`);
+  if (!pipeline) why.push(`merge requests into ${branch} do not need a passing pipeline`);
+  return { no: why.join('; ') };
+}
+
+/** What vdx asks Bitbucket with, and where it comes from — for the reason when it is refused. */
+interface BitbucketAuth {
+  token: string;
+  scheme: 'Bearer' | 'Basic';
+  source: string;
+}
+
+const MIN_BUILDS = 'com.atlassian.bitbucket.server.bitbucket-build:requiredBuildsMergeCheck';
+
+/** A refusal of Bitbucket as the reason the answer is unknown; null for a 200. */
+function bitbucketRefusal(a: Answer, host: string, repo: string, auth: BitbucketAuth | null): Unknown | null {
+  if (a.status === 200) return null;
+  const message = str(at(list(at(a.body, 'errors'))[0], 'message')) ?? '';
+  if (a.status === 401 && !auth) {
+    return {
+      unknown: `${host} shows ${repo} only after a login — once: git ls-remote https://${host}/scm/${repo}.git, a token as the password; or BITBUCKET_TOKEN with BITBUCKET_HOST`,
+    };
+  }
+  if (a.status === 401) {
+    return { unknown: `${host} refused ${repo} to ${auth?.source} — no access, a changed password, a revoked token?` };
+  }
+  return { unknown: `${host} answered ${a.status} for ${repo}${message ? `: ${message}` : ''}` };
+}
+
+/**
+ * Bitbucket Server: the default branch takes changes only after a build when nothing
+ * reaches it but a pull request — a `pull-request-only` or `read-only` restriction on it
+ * exempts nobody; an exempt user pushes past the build — and a pull request needs a
+ * successful build (the merge check «Minimum successful builds»). Shapes of git.finam.ru,
+ * 5.16.1 (DL #17). The first refusal ends the questions: every login refused brings the
+ * owner's account nearer a CAPTCHA.
+ */
+function judgeBitbucket(io: HostingIo, host: string, path: string, auth: BitbucketAuth | null): Verdict {
+  const [project, slug, ...rest] = path.replace(/^scm\//, '').split('/');
+  if (!project || !slug || rest.length > 0) return { unknown: `${host}: no project and repository in ${path}` };
+  const repo = `${project}/${slug}`;
+  const repoPath = `projects/${encodeURIComponent(project)}/repos/${encodeURIComponent(slug)}`;
+  const api = `https://${host}/rest/api/1.0/${repoPath}`;
+  const ask = (url: string) => (auth ? io.get(url, auth.token, auth.scheme) : io.get(url, null));
+
+  let branch = io.git(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'])?.replace(/^origin\//, '');
+  if (!branch) {
+    const d = ask(`${api}/branches/default`);
+    const refused = bitbucketRefusal(d, host, repo, auth);
+    if (refused) return refused;
+    branch = str(at(d.body, 'displayId'));
+    if (!branch) return { unknown: `${host} names no default branch for ${repo}` };
+  }
+
+  // Whoever reads the repository sees its merge checks; only an admin sees its restrictions.
+  const hooks = ask(`${api}/settings/hooks?type=PRE_PULL_REQUEST_MERGE&limit=100`);
+  const refusedHooks = bitbucketRefusal(hooks, host, repo, auth);
+  if (refusedHooks) return refusedHooks;
+  const builds = list(at(hooks.body, 'values')).some(
+    (h) => at(h, 'details', 'key') === MIN_BUILDS && at(h, 'enabled') === true,
+  );
+  const noBuilds = `pull requests into ${branch} need no successful build`;
+
+  const r = ask(`https://${host}/rest/branch-permissions/2.0/${repoPath}/restrictions?limit=100`);
+  if (r.status !== 200) {
+    // Without the build check the branch takes unbuilt changes, whoever may push to it.
+    if (!builds) return { no: noBuilds };
+    if (r.status === 401 && auth) {
+      return { unknown: `${host} shows who may change ${branch} of ${repo} only to a repository admin` };
+    }
+    return bitbucketRefusal(r, host, repo, auth) ?? { unknown: `${host} answered ${r.status} for ${repo}` };
+  }
+  if (at(r.body, 'isLastPage') === false) return { unknown: `${repo} has more than 100 branch restrictions` };
+
+  let guarded = false;
+  let byPattern = false;
+  const exempt = new Set<string>();
+  for (const x of list(at(r.body, 'values'))) {
+    if (!['read-only', 'pull-request-only'].includes(str(at(x, 'type')) ?? '')) continue;
+    if (at(x, 'matcher', 'type', 'id') !== 'BRANCH') {
+      byPattern = true;
+      continue;
+    }
+    if (at(x, 'matcher', 'id') !== `refs/heads/${branch}`) continue;
+    const who = [
+      ...list(at(x, 'users')).map((u) => str(at(u, 'name')) ?? 'a user'),
+      ...list(at(x, 'groups')).map((g) => `group ${str(g) ?? '?'}`),
+      ...list(at(x, 'accessKeys')).map((k) => `access key ${str(at(k, 'key', 'label')) ?? '?'}`),
+    ];
+    if (who.length === 0) guarded = true;
+    for (const w of who) exempt.add(w);
+  }
+
+  // A pattern or the branching model may cover the branch: vdx does not read them (DL #17).
+  if (!guarded && byPattern && builds) {
+    return {
+      unknown: `a branch restriction by pattern or branching model on ${repo} may cover ${branch} — vdx reads those that name the branch`,
+    };
+  }
+  const why: string[] = [];
+  if (!guarded && !byPattern) {
+    why.push(
+      exempt.size > 0
+        ? `${branch} takes changes without a pull request from ${[...exempt].join(', ')} — they skip the build`
+        : `${branch} is not restricted — whoever may write pushes to it`,
+    );
   }
+  if (!builds) why.push(noBuilds);
+  return why.length > 0 ? { no: why.join('; ') } : true;
 }
 
 /** A remote's repository on GitHub and the token to ask with; unknown, with the reason, when vdx cannot ask. */

package/src/index.ts

@@ -127,9 +127,14 @@ const COMMANDS: Record<string, CommandSpec> = {
     usage: 'vdx audit [project_path] [--rubric <path>] [--stack <stack>] [--format=ansi|markdown|json] [--json]',
     help: `Scores the project (default: cwd) against the rubric and prints the report.
 Reads only. The rubric is the bundled one unless --rubric or $VDX_RUBRIC names another.
-For branch-protection it asks GitHub whether the default branch of origin requires
-a check, with a token from $GH_TOKEN, $GITHUB_TOKEN or gh when there is one;
-VDX_OFFLINE=1 does not ask, and the axis says unknown.
+For branch-protection it asks the hosting of origin whether its default branch
+takes changes only after a check required of everyone: GitHub, with a token from
+$GH_TOKEN, $GITHUB_TOKEN or gh when there is one; GitLab, with glab's token for that host,
+or $GITLAB_TOKEN when the host is $GITLAB_HOST (gitlab.com unless set) — no
+other host gets it; Bitbucket Server, with the login git keeps for that host
+(git credential), or $BITBUCKET_TOKEN when the host is $BITBUCKET_HOST.
+Another hosting is unknown; VDX_OFFLINE=1 does not ask, and the axis says
+unknown.
 `,
     bools: ['json'],
     values: ['rubric', 'stack', 'format'],