cawdev-cli 1.1.0 → 1.2.0

package/runner/git-host.mjs

@@ -3,9 +3,11 @@
 // The runner has only ever spoken to GitHub, through `gh`. A GitLab project
 // could be pushed to but not opened, found or merged against, and a run's link
 // to its pull request came back empty. This is the one place that knows there
-// are two: `adapterFor('github')` is the `gh` calls the daemon always made,
+// are three: `adapterFor('github')` is the `gh` calls the daemon always made,
 // moved here without change; `adapterFor('gitlab')` is the same questions asked
-// of `glab`.
+// of `glab`; `adapterFor('bitbucket')` (R565) asks Bitbucket Cloud's REST API
+// with a token that lives on this machine (`configureBitbucket`), because
+// Bitbucket has no CLI to lean on.
 //
 // No dependencies, and in `tools/runner/` rather than `tools/lib/` on purpose:
 // this half of the tree is open-licence and must not import the other.
@@ -36,17 +38,20 @@ export function repoOf(originUrl) {
 }
 
 /**
- * Which host's CLI to use: `'github'` or `'gitlab'`.
+ * Which host to talk to: `'github'`, `'gitlab'` or `'bitbucket'`.
  *
  * A host the project DECLARED wins; otherwise a host name containing `gitlab` is
- * GitLab; otherwise GitHub, which is what the runner has always assumed — so a
+ * GitLab, `bitbucket.org` is Bitbucket; otherwise GitHub, which is what the
+ * runner has always assumed — so a
  * project that never set anything behaves exactly as it did.
  */
 export function hostFor({ declared = null, originUrl = null } = {}) {
   const said = String(declared ?? '').trim().toUpperCase();
   if (said === 'GITLAB') return 'gitlab';
   if (said === 'GITHUB') return 'github';
+  if (said === 'BITBUCKET') return 'bitbucket';
   const repo = repoOf(originUrl);
+  if (repo && /bitbucket\.org$/i.test(repo.host)) return 'bitbucket';
   return repo && /gitlab/i.test(repo.host) ? 'gitlab' : 'github';
 }
 
@@ -60,6 +65,9 @@ export function compareUrl(host, repo, base, branch) {
     return null;
   }
   const name = encodeURIComponent(branch);
+  if (host === 'bitbucket') {
+    return `https://bitbucket.org/${repo.path}/branches/compare/${name}%0D${encodeURIComponent(base || 'main')}`;
+  }
   if (host === 'gitlab') {
     return `https://${repo.host}/${repo.path}/-/compare/${encodeURIComponent(base || 'main')}...${name}`;
   }
@@ -77,6 +85,11 @@ export function iidOf(url) {
   return /\/merge_requests\/(\d+)/.exec(url ?? '')?.[1] ?? null;
 }
 
+/** The pull request id at the end of a Bitbucket pull request URL. */
+export function prIdOf(url) {
+  return /\/pull-requests\/(\d+)/.exec(url ?? '')?.[1] ?? null;
+}
+
 const GITLAB_WAIT = new Set(['checking', 'unchecked', 'preparing', 'ci_still_running']);
 const GITLAB_BLOCKED = new Set([
   'not_approved', 'blocked_status', 'ci_must_pass', 'discussions_not_resolved',
@@ -131,6 +144,8 @@ function parse(text) {
 
 // --- the adapters ----------------------------------------------------------------
 
+const STATES = { OPEN: 'OPEN', MERGED: 'MERGED', CLOSED: 'CLOSED' };
+
 const github = {
   name: 'github',
   bin: 'gh',
@@ -178,6 +193,36 @@ const github = {
     return null;
   },
 
+  /** `{ state, mergedAt, mergeCommit }` for a pull request URL (or branch), or null. */
+  async view(cwd, target) {
+    const asked = await runCli('gh', cwd, ['pr', 'view', target, '--json', 'state,mergedAt,mergeCommit']);
+    const parsed = asked.code === 0 ? parse(asked.out) : null;
+    if (!parsed?.state) return null;
+    return {
+      state: STATES[parsed.state] ?? null,
+      mergedAt: parsed.mergedAt ?? null,
+      mergeCommit: parsed.mergeCommit?.oid ?? null,
+    };
+  },
+
+  /** Every pull request whose head is `branch`, in the shape all three hosts share. */
+  async listByHead(cwd, branch) {
+    const asked = await runCli('gh', cwd, ['pr', 'list', '--head', branch, '--state', 'all', '--limit', '10', '--json',
+      'number,url,state,mergedAt,mergeCommit,baseRefName,headRefName,isCrossRepository']);
+    const rows = asked.code === 0 ? parse(asked.out) : null;
+    if (!Array.isArray(rows)) return null;
+    return rows.map((row) => ({
+      number: row.number,
+      url: row.url ?? null,
+      state: STATES[row.state] ?? null,
+      mergedAt: row.mergedAt ?? null,
+      mergeCommit: row.mergeCommit?.oid ?? null,
+      baseRefName: row.baseRefName ?? null,
+      headRefName: row.headRefName ?? null,
+      isCrossRepository: Boolean(row.isCrossRepository),
+    }));
+  },
+
   /** The compare link fallback — only for github.com, as it always was. */
   fallbackLink(repo, _base, branch) {
     return repo && repo.host === 'github.com' ? compareUrl('github', repo, null, branch) : null;
@@ -255,9 +300,257 @@ const gitlab = {
     return verdict === 'CONFLICT' || verdict === 'NOT_PERMITTED' ? verdict : null;
   },
 
+  async view(cwd, target) {
+    const asked = await runCli('glab', cwd, ['mr', 'view', iidOf(target) ?? target, '--output', 'json']);
+    const row = asked.code === 0 ? parse(asked.out) : null;
+    if (!row?.state) return null;
+    const { state, mergedAt, mergeCommit } = gitlabRow(row);
+    return state ? { state, mergedAt, mergeCommit } : null;
+  },
+
+  async listByHead(cwd, branch) {
+    // `--all` is newer than some installs; without it, ask for merged and closed
+    // separately and join them to the open ones.
+    if (glabHasAll === null) {
+      const help = await runCli('glab', cwd, ['mr', 'list', '--help']);
+      if (help.code === 0) glabHasAll = /--all\b/.test(`${help.out}\n${help.err}`);
+    }
+    const ask = (...flags) => runCli('glab', cwd,
+      ['mr', 'list', '--source-branch', branch, ...flags, '--output', 'json']);
+    const asked = glabHasAll === false ? null : await ask('--all');
+    const lists = asked
+      ? [asked]
+      : await Promise.all([ask(), ask('--merged'), ask('--closed')]);
+    const rows = [];
+    for (const one of lists) {
+      const parsed = one.code === 0 ? parse(one.out) : null;
+      if (Array.isArray(parsed)) rows.push(...parsed);
+    }
+    if (!rows.length && lists.every((one) => one.code !== 0)) return null;
+    return rows.map((row) => gitlabRow(row));
+  },
+
   fallbackLink: (repo, base, branch) => compareUrl('gitlab', repo, base, branch),
 };
 
+let glabHasAll = null;
+
+/** A merge request as the shared row. A squash merge's commit is `squash_commit_sha`. */
+function gitlabRow(row) {
+  return {
+    number: row.iid ?? null,
+    url: row.web_url ?? null,
+    state: { opened: 'OPEN', merged: 'MERGED', closed: 'CLOSED', locked: 'OPEN' }[row.state] ?? null,
+    mergedAt: row.merged_at ?? null,
+    mergeCommit: row.merge_commit_sha ?? row.squash_commit_sha ?? null,
+    baseRefName: row.target_branch ?? null,
+    headRefName: row.source_branch ?? null,
+    isCrossRepository: row.source_project_id != null && row.source_project_id !== row.target_project_id,
+  };
+}
+
+// --- Bitbucket Cloud --------------------------------------------------------------
+//
+// No CLI: the REST API, with a token this machine keeps (`configureBitbucket`,
+// from the runner's own config). The platform never sees it, and the agent's
+// environment has it removed (`agentEnv` in runner.mjs).
+
+let bitbucketSettings = { email: null, token: null, apiUrl: 'https://api.bitbucket.org/2.0' };
+
+/** Called once at boot, and by tests. `apiUrl` is only for tests. */
+export function configureBitbucket({ email = null, token = null, apiUrl = null } = {}) {
+  bitbucketSettings = {
+    email: email || null,
+    token: token || null,
+    apiUrl: (apiUrl || 'https://api.bitbucket.org/2.0').replace(/\/+$/, ''),
+  };
+}
+
+const NO_TOKEN = 'Bitbucket needs an API token on this machine. Set "bitbucket": { "email": "…", '
+  + '"tokenEnv": "BITBUCKET_TOKEN" } in this machine\'s cawdev config and export the token.';
+
+/** `{ status, json, headers }`, or `{ status: -1, error }` when the call never landed. */
+async function bitbucketCall(method, url, body) {
+  const { email, token } = bitbucketSettings;
+  const auth = email
+    ? `Basic ${Buffer.from(`${email}:${token}`).toString('base64')}`
+    : `Bearer ${token}`;
+  try {
+    const response = await fetch(url, {
+      method,
+      headers: {
+        Authorization: auth,
+        Accept: 'application/json',
+        ...(body ? { 'Content-Type': 'application/json' } : {}),
+      },
+      body: body ? JSON.stringify(body) : undefined,
+      redirect: 'manual',
+      signal: AbortSignal.timeout(30_000),
+    });
+    const text = await response.text();
+    return { status: response.status, json: parse(text), headers: response.headers };
+  } catch (failure) {
+    return { status: -1, error: failure.message };
+  }
+}
+
+/** `{ base, ws, repo }` for the checkout's origin, or an error result. */
+async function bitbucketRepo(cwd) {
+  if (!bitbucketSettings.token) {
+    return { failure: { code: -1, out: '', err: NO_TOKEN } };
+  }
+  const origin = await runCli('git', cwd, ['remote', 'get-url', 'origin']);
+  const repo = origin.code === 0 ? repoOf(origin.out) : null;
+  const [ws, slug] = (repo?.path ?? '').split('/');
+  if (!ws || !slug) {
+    return { failure: { code: 1, out: '', err: 'Could not read the Bitbucket workspace and repository from origin.' } };
+  }
+  return { base: `${bitbucketSettings.apiUrl}/repositories/${ws}/${slug}` };
+}
+
+function bitbucketProblem(reply) {
+  if (reply.status === -1) return reply.error;
+  return reply.json?.error?.message ?? `Bitbucket answered ${reply.status}`;
+}
+
+const BITBUCKET_STATES = { OPEN: 'OPEN', MERGED: 'MERGED', DECLINED: 'CLOSED', SUPERSEDED: 'CLOSED' };
+
+function bitbucketRow(row) {
+  const state = BITBUCKET_STATES[row.state] ?? null;
+  return {
+    number: row.id ?? null,
+    url: row.links?.html?.href ?? null,
+    state,
+    mergedAt: state === 'MERGED' ? (row.updated_on ?? null) : null,
+    mergeCommit: row.merge_commit?.hash ?? null,
+    baseRefName: row.destination?.branch?.name ?? null,
+    headRefName: row.source?.branch?.name ?? null,
+    isCrossRepository: row.source?.repository?.full_name !== row.destination?.repository?.full_name
+      && Boolean(row.source?.repository?.full_name),
+  };
+}
+
+/** A value inside a Bitbucket query's double quotes. */
+const quoted = (value) => String(value).replace(/[\\"]/g, '\\$&');
+
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+
+const bitbucket = {
+  name: 'bitbucket',
+  bin: null,
+  noun: 'pull request',
+  installHint: 'set "bitbucket": { "email": "…", "tokenEnv": "BITBUCKET_TOKEN" } in this machine\'s cawdev config and export the token',
+
+  async run() {
+    return { code: -1, out: '', err: 'Bitbucket has no command line here; cawdev calls its API directly.' };
+  },
+
+  async find(cwd, branch) {
+    const where = await bitbucketRepo(cwd);
+    if (where.failure) return null;
+    const q = encodeURIComponent(`source.branch.name="${quoted(branch)}" AND state="OPEN"`);
+    const reply = await bitbucketCall('GET', `${where.base}/pullrequests?q=${q}`);
+    return reply.status === 200 ? (reply.json?.values?.[0]?.links?.html?.href ?? null) : null;
+  },
+
+  async create(cwd, { branch, base, title, body }) {
+    const where = await bitbucketRepo(cwd);
+    if (where.failure) return where.failure;
+    const reply = await bitbucketCall('POST', `${where.base}/pullrequests`, {
+      title,
+      description: body,
+      source: { branch: { name: branch } },
+      ...(base ? { destination: { branch: { name: base } } } : {}),
+      close_source_branch: true,
+    });
+    if (reply.status === 201 && reply.json?.links?.html?.href) {
+      return { code: 0, out: reply.json.links.html.href, err: '' };
+    }
+    return { code: 1, out: '', err: bitbucketProblem(reply) };
+  },
+
+  urlOf: (created) => created.out,
+
+  /** Bitbucket does not compute mergeability lazily: there is nothing to wait for. */
+  async mergeability() {
+    return 'KNOWN';
+  },
+
+  async merge(cwd, url, { mergeCommit }) {
+    const where = await bitbucketRepo(cwd);
+    if (where.failure) return where.failure;
+    const id = prIdOf(url);
+    if (!id) return { code: 1, out: '', err: `Not a Bitbucket pull request URL: ${url}` };
+    const reply = await bitbucketCall('POST', `${where.base}/pullrequests/${id}/merge`, {
+      merge_strategy: mergeCommit ? 'merge_commit' : 'squash',
+      close_source_branch: true,
+    });
+    if (reply.status === 200) {
+      return { code: 0, out: reply.json?.links?.html?.href ?? url, err: '' };
+    }
+    if (reply.status !== 202) {
+      return { code: 1, out: '', err: bitbucketProblem(reply) };
+    }
+    // 202: the merge runs as a background task; its URL is in Location.
+    const task = reply.headers.get('location');
+    // Only ever follow it on the API we were talking to: the poll carries our token.
+    if (task && !task.startsWith(bitbucketSettings.apiUrl) && !task.startsWith(new URL(bitbucketSettings.apiUrl).origin)) {
+      return { code: 1, out: '', err: 'Bitbucket accepted the merge but pointed at a task on another host; not following it.' };
+    }
+    if (!task) return { code: 1, out: '', err: 'Bitbucket accepted the merge but gave no task to follow.' };
+    const wait = Number(process.env.CAWDEV_MERGEABILITY_WAIT_MS ?? 5000);
+    for (let attempt = 0; attempt < 6; attempt += 1) {
+      await sleep(wait);
+      const polled = await bitbucketCall('GET', task);
+      const status = polled.json?.task_status;
+      if (status === 'SUCCESS') return { code: 0, out: url, err: '' };
+      if (status === 'FAILED') {
+        return { code: 1, out: '', err: polled.json?.merge_result?.error?.message ?? polled.json?.error?.message ?? 'Bitbucket failed to merge the pull request.' };
+      }
+    }
+    return { code: 1, out: '', err: 'Bitbucket is still merging this pull request; check it in a moment.' };
+  },
+
+  async refusal(cwd, url) {
+    const where = await bitbucketRepo(cwd);
+    const id = prIdOf(url);
+    if (where.failure || !id) return null;
+    const reply = await bitbucketCall('GET', `${where.base}/pullrequests/${id}/diffstat`);
+    const values = reply.status === 200 ? reply.json?.values : null;
+    return Array.isArray(values) && values.some((entry) => /conflict/i.test(entry?.status ?? ''))
+      ? 'CONFLICT'
+      : null;
+  },
+
+  async view(cwd, target) {
+    const where = await bitbucketRepo(cwd);
+    if (where.failure) return null;
+    const id = prIdOf(target);
+    if (!id) {
+      // A branch name, not a URL: the newest pull request from it.
+      const rows = await this.listByHead(cwd, target);
+      const newest = rows?.sort((a, b) => b.number - a.number)[0];
+      return newest ? { state: newest.state, mergedAt: newest.mergedAt, mergeCommit: newest.mergeCommit } : null;
+    }
+    const reply = await bitbucketCall('GET', `${where.base}/pullrequests/${id}`);
+    if (reply.status !== 200 || !reply.json) return null;
+    const row = bitbucketRow(reply.json);
+    return row.state ? { state: row.state, mergedAt: row.mergedAt, mergeCommit: row.mergeCommit } : null;
+  },
+
+  async listByHead(cwd, branch) {
+    const where = await bitbucketRepo(cwd);
+    if (where.failure) return null;
+    const q = encodeURIComponent(`source.branch.name="${quoted(branch)}"`);
+    const states = ['OPEN', 'MERGED', 'DECLINED'].map((state) => `state=${state}`).join('&');
+    const reply = await bitbucketCall('GET', `${where.base}/pullrequests?q=${q}&${states}&pagelen=10`);
+    if (reply.status !== 200 || !Array.isArray(reply.json?.values)) return null;
+    return reply.json.values.map(bitbucketRow);
+  },
+
+  fallbackLink: (repo, base, branch) => compareUrl('bitbucket', repo, base, branch),
+};
+
 export function adapterFor(host) {
-  return host === 'gitlab' ? gitlab : github;
+  return host === 'gitlab' ? gitlab : host === 'bitbucket' ? bitbucket : github;
 }

package/runner/pause-note.mjs

@@ -0,0 +1,104 @@
+// What a queued run's note says when this machine is paused — R571.
+//
+// Pure, zero dependencies, so `node --test` pins the two sentences. There are
+// two kinds of pause and they have different ways out: one a person made (R73:
+// Settings → Machines, or `c` in an attached terminal) and one cawdev made for
+// usage (R158: it lifts itself when the window resets, and a Resume would be
+// undone within the minute while the machine is still over the line).
+//
+// The usage sentence is a second implementation of the console's
+// (`runners/pause-words.ts`) across the zero-dependency boundary. Both read the
+// server's `percent`, never recompute it.
+
+/** The fullest whole window (no `model`) with a reading, or null. */
+export function worstWindow(limits) {
+  const whole = (Array.isArray(limits) ? limits : [])
+    .filter((limit) => limit && !limit.model && Number.isFinite(limit.percent));
+  if (!whole.length) {
+    return null;
+  }
+  return whole.reduce((worst, each) => (each.percent > worst.percent ? each : worst));
+}
+
+/** `1h 20m` · `12m` · `under a minute`. */
+export function inWords(ms) {
+  if (!Number.isFinite(ms) || ms < 60_000) {
+    return 'under a minute';
+  }
+  const minutes = Math.floor(ms / 60_000);
+  if (minutes < 60) {
+    return `${minutes}m`;
+  }
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) {
+    return minutes % 60 ? `${hours}h ${minutes % 60}m` : `${hours}h`;
+  }
+  return hours % 24 ? `${Math.floor(hours / 24)}d ${hours % 24}h` : `${Math.floor(hours / 24)}d`;
+}
+
+/**
+ * The queued line for a paused machine.
+ *
+ * @param {{ pausedByUsage?: boolean, limits?: object[] }} machine what the heartbeat said
+ * @param {number} now milliseconds
+ */
+export function pausedNote({ pausedByUsage = false, limits = [] } = {}, now = Date.now()) {
+  if (!pausedByUsage) {
+    return 'this machine is paused from the console '
+      + '(resume it on Settings → Machines, or press c)';
+  }
+  const worst = worstWindow(limits);
+  if (!worst) {
+    return 'cawdev paused this machine for usage — it resumes by itself when the window resets';
+  }
+  const name = worst.window === 'WEEKLY' ? 'weekly' : 'five-hour';
+  const resets = worst.resetsAt ? Date.parse(worst.resetsAt) : NaN;
+  const back = Number.isFinite(resets) ? `, back in ${inWords(resets - now)}` : '';
+  return `cawdev paused this machine for usage: its ${name} window is at ${worst.percent}%${back}`
+    + ' — it resumes by itself';
+}
+
+/**
+ * The key a note changes on: the kind of pause, the window and its percent and
+ * reset — never the minutes left, which would change the sentence every
+ * heartbeat and make the log chatter.
+ */
+export function noteKey({ pausedByUsage = false, limits = [] } = {}) {
+  if (!pausedByUsage) {
+    return 'hand';
+  }
+  const worst = worstWindow(limits);
+  return worst ? `usage:${worst.window}:${worst.percent}:${worst.resetsAt ?? ''}` : 'usage';
+}
+
+/**
+ * The heartbeat's change line, or null when nothing about the pause moved.
+ *
+ * @param {{ paused: boolean, pausedByUsage: boolean }} before
+ * @param {{ paused?: boolean, pausedByUsage?: boolean }} after
+ */
+export function pauseLogLine(before, after) {
+  const paused = !!after.paused;
+  const byUsage = paused && !!after.pausedByUsage;
+  if (before.paused === paused && before.pausedByUsage === byUsage) {
+    return null;
+  }
+  if (!paused) {
+    return before.pausedByUsage
+      ? 'cawdev lifted the usage pause: claiming again'
+      : 'unpaused from the console';
+  }
+  return byUsage
+    ? 'cawdev paused this machine for usage: claiming nothing new, finishing what is running'
+    : 'paused from the console: claiming nothing new, finishing what is running';
+}
+
+/**
+ * What the platform is told about a pause: nothing. The queued-reasons call is
+ * served to EVERY project viewer as `queuedReason`, so the usage figures and
+ * "press c" stay in this daemon's log and terminal; the platform says it
+ * itself, per viewer, as `waitingOn` (R571).
+ */
+export function reportedPauseNote() {
+  return null;
+}