Ship

node_modules/
bun.lock

{
  "name": "ship-skill",
  "private": true,
  "type": "module",
  "description": "Runtime deps for the ship skill's TypeScript scripts (run via bun).",
  "dependencies": {
    "@octokit/rest": "^21.1.1",
    "azure-devops-node-api": "^14.1.0"
  },
  "devDependencies": {
    "@types/node": "^22.10.5",
    "typescript": "^5.7.3"
  }
}

#!/usr/bin/env bun
// Print the delivery platform and coordinates for a remote, as key=value lines.
// Usage: bun ship-detect.ts [remote]   (default remote: origin)

import { currentBranch, remoteUrl, detectKind, adoParts, parseWorkItem } from "./ship-lib.ts";

const remote = process.argv[2] ?? "origin";
const url = remoteUrl(remote);
const kind = detectKind(url);

console.log(`platform=${kind}`);
console.log(`remote=${remote}`);
console.log(`url=${url}`);
console.log(`branch=${currentBranch()}`);

if (kind === "azure") {
  const parts = adoParts(url);
  if (parts) {
    console.log(`org_url=${parts.orgUrl}`);
    console.log(`project=${parts.project}`);
    console.log(`repo=${parts.repo}`);
  }
}

const wi = parseWorkItem();
if (wi) console.log(`work_item=${wi}`);

// Shared helpers for the `ship` skill (TypeScript, run via bun).
// Import these; do not execute this file directly.
//
// Git/branch/remote work stays as subprocess calls — it is inherently a git
// operation, not an API one. The Azure DevOps and GitHub REST surfaces use their
// official SDKs (azure-devops-node-api, @octokit/rest). All subprocess calls go
// through execFile with an argument array — never a shell string — so nothing is
// interpolated into a shell.

import { execFileSync } from "node:child_process";
import * as azdev from "azure-devops-node-api";

export type Platform = "azure" | "github" | "unknown";

export interface AdoParts {
  orgUrl: string;
  project: string;
  repo: string;
}

/** Run a command with an argument array (no shell). Returns trimmed stdout.
 *  With { allowFail: true }, a non-zero exit yields "" instead of throwing. */
export function sh(cmd: string, args: string[], opts: { allowFail?: boolean } = {}): string {
  try {
    return execFileSync(cmd, args, { encoding: "utf8" }).trim();
  } catch (err) {
    if (opts.allowFail) return "";
    throw err;
  }
}

/** Current checked-out branch name. */
export function currentBranch(): string {
  return sh("git", ["rev-parse", "--abbrev-ref", "HEAD"]);
}

/** Fetch URL of a remote (default: origin). Empty string if the remote is unset. */
export function remoteUrl(remote = "origin"): string {
  return sh("git", ["remote", "get-url", remote], { allowFail: true });
}

/** Classify a remote URL. Override with SHIP_PLATFORM=azure|github when detection
 *  is wrong (e.g. a custom SSH host alias that hides the real host). */
export function detectKind(url: string = remoteUrl()): Platform {
  const override = process.env.SHIP_PLATFORM;
  if (override === "azure" || override === "github") return override;
  if (/dev\.azure\.com|visualstudio\.com/.test(url)) return "azure";
  if (/github/.test(url)) return "github";
  return "unknown";
}

/** Parse an Azure DevOps remote URL into org URL / project / repo.
 *  Handles HTTPS (dev.azure.com), SSH (ssh.dev.azure.com:v3/...), and legacy
 *  *.visualstudio.com. Returns null if the URL is not an Azure DevOps URL. */
export function adoParts(url: string = remoteUrl()): AdoParts | null {
  let m = url.match(/dev\.azure\.com[^:/\s]*[:/]+(?:v3\/)?([^/]+)\/([^/]+)\/(?:_git\/)?([^/]+)$/);
  if (m) return { orgUrl: `https://dev.azure.com/${m[1]}`, project: m[2], repo: m[3].replace(/\.git$/, "") };
  m = url.match(/([^/@.]+)\.visualstudio\.com\/([^/]+)\/(?:_git\/)?([^/]+)$/);
  if (m) return { orgUrl: `https://dev.azure.com/${m[1]}`, project: m[2], repo: m[3].replace(/\.git$/, "") };
  return null;
}

/** Mint a short-lived Azure DevOps OAuth access token via the logged-in az CLI.
 *  499b84ac-1321-427f-aa17-267ca6975798 is the constant Azure DevOps API resource
 *  id (not a secret — the same for every org). Used as a git Bearer header and as
 *  the bearer for the azure-devops-node-api WebApi connection. */
export function adoToken(): string {
  return sh("az", [
    "account", "get-access-token",
    "--resource", "499b84ac-1321-427f-aa17-267ca6975798",
    "--query", "accessToken", "-o", "tsv",
  ]);
}

/** True if an SDK error is a 401/403 — the signal to fall back from a PAT to the
 *  az OAuth bearer (an under-scoped PAT fails write calls a full org member can make). */
export function isAuthError(e: any): boolean {
  const code = e?.statusCode ?? e?.status;
  if (code === 401 || code === 403) return true;
  return /\((?:401|403)\)/.test(String(e?.message ?? e));
}

/** Build an Azure DevOps WebApi connection. Prefers a configured PAT
 *  (AZURE_DEVOPS_EXT_PAT / AZURE_DEVOPS_PAT, the standard `az devops` credential);
 *  otherwise mints an az OAuth bearer. `usingPat` lets the caller retry with the
 *  bearer on a 401/403 — see isAuthError and the authFallback pattern in ship-pr.ts. */
export function adoConnection(
  orgUrl: string,
  opts: { forceBearer?: boolean } = {},
): { conn: azdev.WebApi; usingPat: boolean } {
  const pat = opts.forceBearer ? "" : (process.env.AZURE_DEVOPS_EXT_PAT || process.env.AZURE_DEVOPS_PAT);
  const handler = pat ? azdev.getPersonalAccessTokenHandler(pat) : azdev.getBearerHandler(adoToken());
  return { conn: new azdev.WebApi(orgUrl, handler), usingPat: !!pat };
}

/** Split a CSV/repeated-flag tag list into clean, de-duplicated names.
 *  Drops empty/whitespace entries so they never reach the label API. */
export function parseTags(values: string[]): string[] {
  const out: string[] = [];
  for (const v of values) {
    for (const part of v.split(",")) {
      const name = part.trim();
      if (name && !out.includes(name)) out.push(name);
    }
  }
  return out;
}

/** Best-effort extraction of a work-item id from a branch name or commit subject.
 *  Recognizes `AB#1234`, `AB1234`, and a number delimited by / _ - (e.g.
 *  feature/1234-foo). Returns the id or "". Heuristic — confirm it exists before
 *  trusting it (see adoWorkItemExists in ship-pr.ts). */
export function parseWorkItem(s: string = currentBranch()): string {
  let m = s.match(/[Aa][Bb]#?(\d{1,7})/);
  if (m) return m[1];
  m = s.match(/(?:^|[/_-])(\d{2,7})(?:[/_-]|$)/);
  if (m) return m[1];
  return "";
}

#!/usr/bin/env bun
// Open a pull request on the detected platform (Azure Repos via azure-devops-node-api,
// GitHub via @octokit/rest), link work item(s), and optionally transition Board state.
//
// Usage:
//   bun ship-pr.ts --title T [--body B | --body-file F] [--target main] [--source BR]
//                  [--work-item ID] [--task "title" ...] [--tasks-file F]
//                  [--assignee UPN] [--work-item-type TYPE] [--no-create-work-item]
//                  [--transition STATE] [--tag "t1,t2" ...] [--draft] [-r remote]
//
// Work-item association (Azure Repos + Boards):
//   On Azure, the PR is always linked to at least one Board work item. The id is
//   taken from --work-item (or inferred from the branch) and VERIFIED to exist. If
//   no real work item is found, one is CREATED per task (each assigned to the
//   configured user) and linked to the PR — so a PR is never opened without
//   traceability.
//
// --work-item   Existing Board id to link. Verified via the SDK; if it doesn't
//               resolve, the create path runs instead.
// --task        Title for a work item to create (repeatable — one item per task).
//               With none given and no work item found, one item is created from
//               the PR --title.
// --tasks-file  File with one task title per line (combined with --task flags).
// --assignee    UPN/email the created work items are assigned to. Default:
//               $SHIP_ADO_ASSIGNEE, else juliano.barbosa@hypera.com.br.
// --work-item-type  Type for created items (default: Task; e.g. "User Story", Bug).
// --no-create-work-item  Disable auto-creation; link only a pre-existing --work-item.
// --transition  Azure only: sets each linked/created item's state AFTER the PR is
//               created (e.g. Resolved). Skipped on GitHub.
// --tag         PR tag(s) to apply after the PR opens (Azure "tags" / GitHub
//               "labels"). Comma-separated and/or repeatable. e.g. --tag hotfix,WIP.
//               Or manage tags later with ship-tag.ts.

import { readFileSync } from "node:fs";
import * as azdev from "azure-devops-node-api";
import { Octokit } from "@octokit/rest";
import {
  sh, currentBranch, remoteUrl, detectKind, adoParts, adoToken, parseWorkItem, parseTags,
} from "./ship-lib.ts";

function fail(msg: string, code = 1): never {
  console.error(msg);
  process.exit(code);
}

// ---- args ----
let title = "", body = "", bodyFile = "", target = "main", sourceBranch = "";
let workItem = "", transition = "", remote = "origin", wiType = "Task";
let assignee = process.env.SHIP_ADO_ASSIGNEE || "juliano.barbosa@hypera.com.br";
let draft = false, createWi = true;
const tasks: string[] = [];
const tagFlags: string[] = [];

const argv = process.argv.slice(2);
for (let i = 0; i < argv.length; i++) {
  const a = argv[i];
  switch (a) {
    case "--title": title = argv[++i]; break;
    case "--body": body = argv[++i]; break;
    case "--body-file": bodyFile = argv[++i]; break;
    case "--target": target = argv[++i]; break;
    case "--source": sourceBranch = argv[++i]; break;
    case "--work-item": workItem = argv[++i]; break;
    case "--task": tasks.push(argv[++i]); break;
    case "--tasks-file":
      for (const line of readFileSync(argv[++i], "utf8").split("\n")) {
        const t = line.trim();
        if (t) tasks.push(t);
      }
      break;
    case "--assignee": assignee = argv[++i]; break;
    case "--work-item-type": wiType = argv[++i]; break;
    case "--no-create-work-item": createWi = false; break;
    case "--transition": transition = argv[++i]; break;
    case "--tag": { const v = argv[++i]; if (v === undefined) fail("--tag requires a value", 2); tagFlags.push(v); break; }
    case "--draft": draft = true; break;
    case "-r": case "--remote": remote = argv[++i]; break;
    case "-h": case "--help":
      console.log(readFileSync(new URL(import.meta.url), "utf8")
        .split("\n").filter((l) => l.startsWith("//")).map((l) => l.slice(3)).join("\n"));
      process.exit(0);
    default: fail(`unknown arg: ${a}`, 2);
  }
}
if (!title) fail("--title is required", 2);
if (!sourceBranch) sourceBranch = currentBranch();
if (!workItem) workItem = parseWorkItem(sourceBranch);

const url = remoteUrl(remote);
const kind = detectKind(url);
if (bodyFile) body = readFileSync(bodyFile, "utf8");
const tags = parseTags(tagFlags);

async function runAzure(): Promise<void> {
  const parts = adoParts(url);
  if (!parts) fail(`could not parse org/project/repo from ${url}`);
  const { orgUrl, project, repo } = parts!;

  // Prefer a configured PAT (the standard ADO credential, used by `az devops`).
  // The az-OAuth token only works when the logged-in az identity is an org member;
  // when it differs from the ADO identity it resolves to anonymous (TF400813).
  const pat = process.env.AZURE_DEVOPS_EXT_PAT || process.env.AZURE_DEVOPS_PAT;
  const handler = pat ? azdev.getPersonalAccessTokenHandler(pat) : azdev.getBearerHandler(adoToken());
  const conn = new azdev.WebApi(orgUrl, handler);
  let wit = await conn.getWorkItemTrackingApi();
  let git = await conn.getGitApi();
  let usingPat = !!pat;

  // A PAT that is present but under-scoped (e.g. Code-only, missing Work Items /
  // Pull Request write) makes the write calls below 401 even though the az OAuth
  // identity may be a full org member. Detect that and retry once with the bearer.
  const isAuthError = (e: any): boolean => {
    const code = e?.statusCode ?? e?.status;
    if (code === 401 || code === 403) return true;
    return /\((?:401|403)\)/.test(String(e?.message ?? e));
  };
  const authFallback = async <T>(op: () => Promise<T>): Promise<T> => {
    try {
      return await op();
    } catch (e) {
      if (!usingPat || !isAuthError(e)) throw e;
      console.error(">> PAT auth failed (401/403); falling back to az OAuth bearer token");
      const bconn = new azdev.WebApi(orgUrl, azdev.getBearerHandler(adoToken()));
      wit = await bconn.getWorkItemTrackingApi();
      git = await bconn.getGitApi();
      usingPat = false;
      return await op();
    }
  };

  // Resolve the work item(s) to link: verify any inferred/passed id exists,
  // otherwise create one per task (each assigned to `assignee`).
  const wiIds: number[] = [];
  const existing = workItem ? Number(workItem) : NaN;
  let exists = false;
  if (!Number.isNaN(existing)) {
    try { exists = !!(await authFallback(() => wit.getWorkItem(existing)))?.id; } catch { exists = false; }
  }

  if (exists) {
    wiIds.push(existing);
    console.error(`>> linking existing work item ${existing}`);
  } else if (createWi) {
    const titles = tasks.length ? tasks : [title];
    for (const t of titles) {
      const document: any[] = [{ op: "add", path: "/fields/System.Title", value: t }];
      if (assignee) document.push({ op: "add", path: "/fields/System.AssignedTo", value: assignee });
      const created = await authFallback(() => wit.createWorkItem(null, document, project, wiType));
      const id = created.id!;
      console.error(`>> created ${wiType} #${id} assigned to ${assignee || "<unassigned>"}: ${t}`);
      console.log(`work_item_created=${id}`);
      wiIds.push(id);
    }
  } else if (workItem) {
    console.error(`>> WARNING: work item ${workItem} not found and --no-create-work-item set; PR will not link it`);
  }

  // Back-fill the AB#<...> placeholder (from assets/pr-template.md) with the resolved
  // id(s), so the work-item reference renders as a live link instead of literal text.
  if (wiIds.length && /AB#<[^>]*>/.test(body)) {
    body = body.replace(/AB#<[^>]*>/g, wiIds.map((id) => `AB#${id}`).join(" "));
    console.error(`>> substituted AB# placeholder -> ${wiIds.map((id) => `AB#${id}`).join(" ")}`);
  }

  const pr = await authFallback(() => git.createPullRequest(
    {
      sourceRefName: `refs/heads/${sourceBranch}`,
      targetRefName: `refs/heads/${target}`,
      title,
      description: body || undefined,
      isDraft: draft || undefined,
      workItemRefs: wiIds.map((id) => ({ id: String(id) })),
    },
    repo,
    project,
  ));

  const prId = pr.pullRequestId!;
  console.log("platform=azure");
  console.log(`pr_id=${prId}`);
  console.log(`pr_url=${orgUrl}/${project}/_git/${repo}/pullrequest/${prId}`);
  if (wiIds.length) console.log(`work_items=${wiIds.join(" ")}`);

  if (transition && wiIds.length) {
    for (const id of wiIds) {
      console.error(`>> transitioning work item ${id} -> ${transition}`);
      await authFallback(() => wit.updateWorkItem(null, [{ op: "add", path: "/fields/System.State", value: transition }], id, project));
      console.log(`work_item=${id} state=${transition}`);
    }
  }

  for (const name of tags) {
    await authFallback(() => git.createPullRequestLabel({ name }, repo, prId, project));
    console.log(`tag_added=${name}`);
  }
}

async function runGitHub(): Promise<void> {
  const m = url.match(/github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?$/);
  if (!m) fail(`could not parse owner/repo from ${url}`);
  const [, owner, repo] = m!;
  const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN || sh("gh", ["auth", "token"], { allowFail: true });
  if (!token) fail("no GitHub token: set GH_TOKEN/GITHUB_TOKEN or run `gh auth login`");

  const octokit = new Octokit({ auth: token });
  const { data } = await octokit.pulls.create({
    owner, repo, base: target, head: sourceBranch, title,
    body: body || undefined, draft,
  });
  console.log("platform=github");
  console.log(`pr_url=${data.html_url}`);
  console.log(`pr_number=${data.number}`);

  if (tags.length) {
    // A PR is an issue on GitHub; labels go through the issues API. A missing
    // label is auto-created on the repo (random color).
    await octokit.issues.addLabels({ owner, repo, issue_number: data.number, labels: tags });
    for (const name of tags) console.log(`tag_added=${name}`);
  }
}

async function main(): Promise<void> {
  switch (kind) {
    case "azure": await runAzure(); break;
    case "github": await runGitHub(); break;
    default: fail(`unknown platform for remote '${remote}' (${url}); set SHIP_PLATFORM=azure|github`);
  }
}

main().catch((err) => fail(err?.message ? `ship-pr failed: ${err.message}` : String(err)));

#!/usr/bin/env bun
// Push the current (or named) branch and set upstream.
// On Azure DevOps, if the normal push fails on auth, mint an OAuth token and
// retry with a Bearer header — the fallback for when SSH and the HTTPS
// credential helper are both unavailable but `az` is logged in.
//
// Usage: bun ship-push.ts [-r remote] [-b branch]

import { execFileSync } from "node:child_process";
import { currentBranch, remoteUrl, detectKind, adoToken } from "./ship-lib.ts";

function fail(msg: string, code = 1): never {
  console.error(msg);
  process.exit(code);
}

// Run git with inherited stdio so push progress streams. Returns true on success.
function git(args: string[]): boolean {
  try {
    execFileSync("git", args, { stdio: "inherit" });
    return true;
  } catch {
    return false;
  }
}

let remote = "origin";
let branch = "";
const argv = process.argv.slice(2);
for (let i = 0; i < argv.length; i++) {
  switch (argv[i]) {
    case "-r": case "--remote": remote = argv[++i]; break;
    case "-b": case "--branch": branch = argv[++i]; break;
    case "-h": case "--help":
      console.log("Usage: bun ship-push.ts [-r remote] [-b branch]");
      process.exit(0);
    default: fail(`unknown arg: ${argv[i]}`, 2);
  }
}
if (!branch) branch = currentBranch();

const url = remoteUrl(remote);
const kind = detectKind(url);
console.error(`>> pushing ${branch} -> ${remote} (${kind})`);

if (git(["push", "-u", remote, branch])) {
  console.log("push_ok=normal");
  process.exit(0);
}

if (kind !== "azure") {
  fail("push failed and remote is not Azure DevOps; not attempting OAuth fallback");
}

console.error(">> normal push failed; trying Azure DevOps OAuth Bearer fallback");
let token: string;
try {
  token = adoToken();
} catch {
  fail("failed to mint token (is 'az login' done?)");
}
if (!token) fail("failed to mint token (is 'az login' done?)");

// Token is passed as a request header, never in the URL. It is short-lived (~60 min).
if (!git(["-c", `http.extraHeader=Authorization: Bearer ${token}`, "push", "-u", remote, branch])) {
  fail("OAuth Bearer push also failed");
}
console.log("push_ok=oauth-bearer");

#!/usr/bin/env bun
// Save the current state as an annotated git tag — a lightweight checkpoint you
// can return to. The tag points at HEAD; the working tree doesn't matter.
//
// The name auto-fills from the date so it's never stale, and the first message
// paragraph auto-fills branch + short hash so the tag is self-describing even if
// you pass no message. Extra -m paragraphs (what changed, verification) are
// yours to supply. This is a *git tag* (a commit checkpoint), distinct from
// ship-tag.ts, which manages PR labels/tags — different concept entirely.
//
// Usage:
//   bun ship-snapshot.ts [-m "para"]... [--daily] [--name <tag>] [--push] [--annotate-note "..."]
//
//   -m, --message "<text>"   Extra message paragraph (repeatable). Each becomes
//                            its own blank-line-separated paragraph in the tag.
//   --daily                  Name = v<YYYY.MM.DD> (one tag/day). Default includes
//                            -HHMM so multiple snapshots/day don't collide.
//   --name <tag>             Use this exact tag name, ignoring the date scheme.
//   --push                   Push the tag to origin after creating it (Azure
//                            OAuth Bearer fallback on auth failure, like ship-push).
//   -h, --help               Show usage.
//
// Output (stdout): tag=<name>  commit=<shorthash>  branch=<branch>  pushed=<yes|no>

import { execFileSync } from "node:child_process";
import { sh, currentBranch, remoteUrl, detectKind, adoToken } from "./ship-lib.ts";

function fail(msg: string, code = 1): never {
  console.error(msg);
  process.exit(code);
}

// git with inherited stdio (push progress streams). Returns true on success.
function gitStreamed(args: string[]): boolean {
  try {
    execFileSync("git", args, { stdio: "inherit" });
    return true;
  } catch {
    return false;
  }
}

let daily = false;
let push = false;
let name = "";
const messages: string[] = [];
const argv = process.argv.slice(2);
for (let i = 0; i < argv.length; i++) {
  switch (argv[i]) {
    case "-m": case "--message": messages.push(argv[++i]); break;
    case "--daily": daily = true; break;
    case "--name": name = argv[++i]; break;
    case "--push": push = true; break;
    case "-h": case "--help":
      console.log(
        'Usage: bun ship-snapshot.ts [-m "para"]... [--daily] [--name <tag>] [--push]',
      );
      process.exit(0);
    default: fail(`unknown arg: ${argv[i]}`, 2);
  }
}

// Must be inside a git repo with a commit to point at.
const head = sh("git", ["rev-parse", "--short", "HEAD"], { allowFail: true });
if (!head) fail("not a git repo, or no commits yet — nothing to snapshot", 2);
const branch = currentBranch();

// Tag name: explicit --name wins; otherwise date-based. `date` (not JS Date) so
// the output matches the shell pattern and respects the machine's local TZ.
if (!name) {
  const fmt = daily ? "+v%Y.%m.%d" : "+v%Y.%m.%d-%H%M";
  name = sh("date", [fmt]);
}

// Refuse to clobber an existing tag — a snapshot must never silently move a tag
// someone else relies on. With the default minute-granular name this only bites
// on two snapshots in the same minute; --daily collides for the rest of the day.
if (sh("git", ["rev-parse", "-q", "--verify", `refs/tags/${name}`], { allowFail: true })) {
  fail(
    `tag '${name}' already exists. Use --name <other>, or drop --daily for minute granularity.`,
    3,
  );
}

// Auto subject makes the tag self-describing even with no -m. Extra paragraphs
// follow. execFileSync (via sh) takes an arg array — no shell — so newlines and
// punctuation in messages are passed through verbatim, never re-interpreted.
const subject = `Snapshot ${name} — ${branch} @ ${head}`;
const tagArgs = ["tag", "-a", name, "-m", subject];
for (const m of messages) tagArgs.push("-m", m);
sh("git", tagArgs);
console.error(`>> created annotated tag ${name} -> ${head} (${branch})`);

let pushed = "no";
if (push) {
  const remote = "origin";
  const kind = detectKind(remoteUrl(remote));
  console.error(`>> pushing tag ${name} -> ${remote} (${kind})`);
  if (gitStreamed(["push", remote, name])) {
    pushed = "yes";
  } else if (kind === "azure") {
    // Mirror ship-push: under-scoped/absent git creds but `az` logged in.
    console.error(">> normal push failed; trying Azure DevOps OAuth Bearer fallback");
    let token = "";
    try { token = adoToken(); } catch { /* handled below */ }
    if (!token) fail("tag created locally, but push failed: could not mint token (is 'az login' done?)");
    if (!gitStreamed(["-c", `http.extraHeader=Authorization: Bearer ${token}`, "push", remote, name])) {
      fail(`tag '${name}' created locally, but OAuth Bearer push also failed`);
    }
    pushed = "yes-oauth-bearer";
  } else {
    fail(`tag '${name}' created locally, but push failed (remote is ${kind}; no OAuth fallback)`);
  }
}

console.log(`tag=${name}`);
console.log(`commit=${head}`);
console.log(`branch=${branch}`);
console.log(`pushed=${pushed}`);

#!/usr/bin/env bun
// Manage tags (Azure DevOps "PR tags" / GitHub PR "labels") on a pull request.
// Tags communicate at-a-glance state to reviewers — work-in-progress, DO NOT
// MERGE, hotfix, area/type — per Microsoft's "Add tags to a pull request" guidance
// (https://learn.microsoft.com/azure/devops/repos/git/pull-requests#add-tags-to-a-pull-request).
//
// Usage:
//   bun ship-tag.ts <pr-id> --add "tag1,tag2" [--add tag3 ...]
//   bun ship-tag.ts <pr-id> --remove "tag1" [--remove tag2 ...]
//   bun ship-tag.ts <pr-id> --list
//   bun ship-tag.ts --pr <pr-id> --add hotfix [-r remote]
//
// <pr-id>      The pull request id. Azure: the numeric PR id (ship-pr.ts prints
//              `pr_id=`). GitHub: the PR number (ship-pr.ts prints `pr_number=`).
// --add T      Tag(s) to add. Comma-separated and/or repeatable. Empty/blank
//              names are dropped. ADO creates the tag definition if new; GitHub
//              auto-creates a missing label (random color) on the repo.
// --remove T   Tag(s) to remove. Comma-separated and/or repeatable.
// --list       Print the PR's current tags, one per line (default if no --add/--remove).
// -r, --remote Git remote to resolve coordinates from (default: origin).
//
// Tags are visible to the team but reversible and low-blast — no destructive
// confirm. Auth mirrors ship-pr.ts: a configured PAT, falling back to an az OAuth
// bearer on a 401/403 (an under-scoped PAT can't write labels a full member can).

import { readFileSync } from "node:fs";
import { Octokit } from "@octokit/rest";
import {
  sh, remoteUrl, detectKind, adoParts, adoConnection, isAuthError, parseTags,
} from "./ship-lib.ts";

function fail(msg: string, code = 1): never {
  console.error(msg);
  process.exit(code);
}

// ---- args ----
let prId = "", remote = "origin", list = false;
const addFlags: string[] = [];
const removeFlags: string[] = [];

const argv = process.argv.slice(2);
let i = 0;
const take = (flag: string): string => {
  const v = argv[++i];
  if (v === undefined) fail(`${flag} requires a value`, 2);
  return v;
};
for (; i < argv.length; i++) {
  const a = argv[i];
  switch (a) {
    case "--pr": prId = take(a); break;
    case "--add": addFlags.push(take(a)); break;
    case "--remove": removeFlags.push(take(a)); break;
    case "--list": list = true; break;
    case "-r": case "--remote": remote = take(a); break;
    case "-h": case "--help":
      console.log(readFileSync(new URL(import.meta.url), "utf8")
        .split("\n").filter((l) => l.startsWith("//")).map((l) => l.slice(3)).join("\n"));
      process.exit(0);
    default:
      if (!prId && /^\d+$/.test(a)) prId = a;
      else fail(`unknown arg: ${a}`, 2);
  }
}
if (!prId) fail("a pull request id is required (positional or --pr)", 2);

const addTags = parseTags(addFlags);
const removeTags = parseTags(removeFlags);
if (!addTags.length && !removeTags.length) list = true; // default action

const url = remoteUrl(remote);
const kind = detectKind(url);

async function runAzure(): Promise<void> {
  const parts = adoParts(url);
  if (!parts) fail(`could not parse org/project/repo from ${url}`);
  const { orgUrl, project, repo } = parts!;
  const id = Number(prId);

  let { conn, usingPat } = adoConnection(orgUrl);
  let git = await conn.getGitApi();
  const authFallback = async <T>(op: () => Promise<T>): Promise<T> => {
    try {
      return await op();
    } catch (e) {
      if (!usingPat || !isAuthError(e)) throw e;
      console.error(">> PAT auth failed (401/403); falling back to az OAuth bearer token");
      ({ conn } = adoConnection(orgUrl, { forceBearer: true }));
      git = await conn.getGitApi();
      usingPat = false;
      return await op();
    }
  };

  for (const name of addTags) {
    await authFallback(() => git.createPullRequestLabel({ name }, repo, id, project));
    console.log(`tag_added=${name}`);
  }
  for (const name of removeTags) {
    try {
      await authFallback(() => git.deletePullRequestLabels(repo, id, name, project));
      console.log(`tag_removed=${name}`);
    } catch (e: any) {
      // a tag that isn't on the PR yields 404 — non-fatal
      console.error(`>> could not remove '${name}': ${e?.message ?? e}`);
    }
  }
  if (list) {
    const labels = await authFallback(() => git.getPullRequestLabels(repo, id, project));
    console.log("platform=azure");
    for (const l of labels) if (l.name) console.log(l.name);
  }
}

async function runGitHub(): Promise<void> {
  const m = url.match(/github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?$/);
  if (!m) fail(`could not parse owner/repo from ${url}`);
  const [, owner, repo] = m!;
  const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN || sh("gh", ["auth", "token"], { allowFail: true });
  if (!token) fail("no GitHub token: set GH_TOKEN/GITHUB_TOKEN or run `gh auth login`");
  const octokit = new Octokit({ auth: token });
  const issue_number = Number(prId); // a PR is an issue on GitHub

  if (addTags.length) {
    await octokit.issues.addLabels({ owner, repo, issue_number, labels: addTags });
    for (const name of addTags) console.log(`tag_added=${name}`);
  }
  for (const name of removeTags) {
    try {
      await octokit.issues.removeLabel({ owner, repo, issue_number, name });
      console.log(`tag_removed=${name}`);
    } catch (e: any) {
      console.error(`>> could not remove '${name}': ${e?.message ?? e}`);
    }
  }
  if (list) {
    const { data } = await octokit.issues.listLabelsOnIssue({ owner, repo, issue_number });
    console.log("platform=github");
    for (const l of data) console.log(l.name);
  }
}

async function main(): Promise<void> {
  switch (kind) {
    case "azure": await runAzure(); break;
    case "github": await runGitHub(); break;
    default: fail(`unknown platform for remote '${remote}' (${url}); set SHIP_PLATFORM=azure|github`);
  }
}

main().catch((err) => fail(err?.message ? `ship-tag failed: ${err.message}` : String(err)));

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "noEmit": true,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "types": ["node"]
  },
  "include": ["scripts/**/*.ts"]
}