@oasissys/bitbucket-cli 0.1.1

package/dist/src/cli.js

@@ -0,0 +1,660 @@
+/**
+ * oasis-bitbucket — AXI CLI for the Oasis Bitbucket Server (git + pull requests).
+ *
+ * Shell-invokable equivalent of the `bitbucket` MCP server. Reuses the same
+ * BitbucketClient, credential storage, and service config so behaviour never
+ * drifts between the two surfaces. Output is TOON on stdout; diagnostics on
+ * stderr; exit codes 0/1/2 (success/error/usage).
+ *
+ * AXI standards: https://toonformat.dev/reference/spec.html
+ */
+import { BitbucketClient } from "./client.js";
+import { loadCreds } from "./storage.js";
+import { getServiceBaseUrl } from "./config.js";
+import { EXIT, emit, emitRaw, fail, binPath, parseArgs, flagStr, flagBool, flagInt, flagList, fieldList, resolveColumns, pick, renderSkillDoc, runSetup, runAuth, } from "./axi.js";
+const DESCRIPTION = "Browse Oasis Bitbucket repos, branches, and pull requests, and manage PRs";
+const BIN = "oasis-bitbucket";
+const DIFF_LINES_DEFAULT = 400; // diff lines shown before truncation
+const DESC_TRUNCATE = 600; // chars of a PR description shown in detail views
+// ─── Shared helpers ─────────────────────────────────────────────────
+function getClient() {
+    const creds = loadCreds("bitbucket");
+    const baseUrl = getServiceBaseUrl("bitbucket", creds?.url);
+    if (!creds?.username || !creds?.password || !baseUrl) {
+        fail("Bitbucket credentials not configured", `Run \`${BIN} auth --user <u> --password <p>\` to sign in`);
+    }
+    return new BitbucketClient(baseUrl, creds.username, creds.password);
+}
+/** Parse the `PROJECT/repo` positional into its parts (slugs never contain `/`). */
+function parseRepoRef(token, usage) {
+    if (!token)
+        fail("a PROJECT/repo reference is required", usage, EXIT.USAGE);
+    const slash = token.indexOf("/");
+    if (slash === -1) {
+        fail(`'${token}' is not a PROJECT/repo reference`, `use PROJECT/repo, e.g. \`${BIN} ${usage.split(" ")[1] ?? "prs"} OCL/common-web-components\``, EXIT.USAGE);
+    }
+    const projectKey = token.slice(0, slash);
+    const repoSlug = token.slice(slash + 1);
+    if (!projectKey || !repoSlug)
+        fail(`'${token}' is not a valid PROJECT/repo reference`, usage, EXIT.USAGE);
+    return { projectKey, repoSlug };
+}
+function requireInt(raw, label, usage) {
+    if (!raw)
+        fail(`${label} is required`, usage, EXIT.USAGE);
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n <= 0)
+        fail(`invalid ${label} '${raw}' (expected a positive number)`, usage, EXIT.USAGE);
+    return n;
+}
+/** Translate BitbucketClient errors into an AXI error and exit. */
+function bail(err, ctx) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const status = /\((\d{3})\)/.exec(msg)?.[1];
+    if (status === "401" || status === "403") {
+        fail("Bitbucket rejected the credentials (401/403)", `Run \`${BIN} auth --user <u> --password <p>\` to update credentials`);
+    }
+    if (status === "404") {
+        if (ctx.prId !== undefined && ctx.ref) {
+            fail(`PR #${ctx.prId} not found in ${ctx.ref.projectKey}/${ctx.ref.repoSlug}`, `Run \`${BIN} prs ${ctx.ref.projectKey}/${ctx.ref.repoSlug}\` to list PRs`);
+        }
+        if (ctx.ref) {
+            fail(`repo '${ctx.ref.projectKey}/${ctx.ref.repoSlug}' not found`, `Run \`${BIN} repos ${ctx.ref.projectKey}\` to list repos in the project`);
+        }
+        if (ctx.project)
+            fail(`project '${ctx.project}' not found or has no repos`);
+    }
+    // Strip the "Bitbucket API error (NNN): " prefix — keep the actionable message.
+    fail(msg.replace(/^Bitbucket API error \(\d+\):\s*/, ""));
+}
+/** Extract `PROJECT/repo` from a PR self-link so home rows are drillable. */
+function repoFromLink(link) {
+    if (!link)
+        return "";
+    const m = /\/projects\/([^/]+)\/repos\/([^/]+)\//.exec(link);
+    return m ? `${m[1]}/${m[2]}` : "";
+}
+function reviewerSummary(reviewers) {
+    if (reviewers.length === 0)
+        return "none";
+    const approved = reviewers.filter(r => r.approved).length;
+    return `${approved}/${reviewers.length} approved`;
+}
+function truncate(text, limit) {
+    const total = text.length;
+    if (total <= limit)
+        return { text, truncated: false, total };
+    return { text: text.slice(0, limit), truncated: true, total };
+}
+function withTimeout(p, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("timeout")), ms);
+        p.then(v => { clearTimeout(timer); resolve(v); }, e => { clearTimeout(timer); reject(e); });
+    });
+}
+// ─── Commands ───────────────────────────────────────────────────────
+async function cmdHome() {
+    const client = getClient();
+    let prs;
+    try {
+        ({ values: prs } = await client.dashboardPullRequests({ state: "OPEN" }));
+    }
+    catch (err) {
+        bail(err, {});
+    }
+    const doc = {
+        bin: binPath(),
+        description: DESCRIPTION,
+        server: getServiceBaseUrl("bitbucket", loadCreds("bitbucket")?.url),
+        prs: "your open pull requests (as author or reviewer)",
+        count: prs.length,
+    };
+    if (prs.length === 0) {
+        doc.open = [];
+        emit(doc);
+        emitRaw("open: 0 open pull requests involving you");
+        emit({ help: [`Run \`${BIN} prs <project>/<repo>\` to list a repo's PRs`] });
+        return;
+    }
+    doc.open = prs.map(pr => ({
+        id: pr.id,
+        repo: repoFromLink(pr.link),
+        title: pr.title,
+        reviews: reviewerSummary(pr.reviewers),
+    }));
+    doc.help = [
+        `Run \`${BIN} pr <project>/<repo> <id>\` to see a PR's details`,
+        `Run \`${BIN} diff <project>/<repo> <id>\` to review its changes`,
+        `Run \`${BIN} prs <project>/<repo>\` to list a repo's PRs`,
+    ];
+    emit(doc);
+}
+const REPO_FIELDS = ["slug", "name", "state", "cloneUrl"];
+const REPO_FIELDS_DEFAULT = ["slug", "name", "state"];
+const PR_FIELDS = ["id", "title", "author", "reviews", "from", "to", "updated", "url"];
+const PR_FIELDS_DEFAULT = ["id", "title", "author", "reviews"];
+async function cmdRepos(parsed) {
+    const project = parsed.positionals[0];
+    if (!project)
+        fail("project key is required", `${BIN} repos <PROJECT>`, EXIT.USAGE);
+    const client = getClient();
+    let result;
+    try {
+        result = await client.listRepos(project);
+    }
+    catch (err) {
+        bail(err, { project });
+    }
+    if (result.values.length === 0) {
+        emit({ project, repos: [] });
+        emitRaw(`repos: 0 repositories found in project '${project}'`);
+        return;
+    }
+    const cols = resolveColumns(REPO_FIELDS, REPO_FIELDS_DEFAULT, fieldList(parsed), `${BIN} repos`);
+    emit({
+        project,
+        count: result.values.length,
+        complete: result.isLastPage,
+        repos: result.values.map(r => pick({ slug: r.slug, name: r.name, state: r.state, cloneUrl: r.cloneUrl ?? "" }, cols)),
+        help: [
+            `Run \`${BIN} prs ${project}/<repo>\` to list a repo's pull requests`,
+            `Run \`${BIN} branches ${project}/<repo>\` to list its branches`,
+        ],
+    });
+}
+async function cmdBranches(parsed) {
+    const ref = parseRepoRef(parsed.positionals[0], `${BIN} branches PROJECT/repo`);
+    const client = getClient();
+    let result;
+    try {
+        result = await client.listBranches(ref.projectKey, ref.repoSlug);
+    }
+    catch (err) {
+        bail(err, { ref });
+    }
+    if (result.values.length === 0) {
+        emit({ repo: `${ref.projectKey}/${ref.repoSlug}`, branches: [] });
+        emitRaw(`branches: 0 branches found in ${ref.projectKey}/${ref.repoSlug}`);
+        return;
+    }
+    emit({
+        repo: `${ref.projectKey}/${ref.repoSlug}`,
+        count: result.values.length,
+        complete: result.isLastPage,
+        branches: result.values.map(b => ({
+            name: b.displayId,
+            default: b.isDefault,
+            commit: b.latestCommit.slice(0, 11),
+        })),
+    });
+}
+async function cmdPrs(parsed) {
+    const ref = parseRepoRef(parsed.positionals[0], `${BIN} prs PROJECT/repo`);
+    const state = (flagStr(parsed, "--state") ?? "OPEN").toUpperCase();
+    const allowed = ["OPEN", "MERGED", "DECLINED", "ALL"];
+    if (!allowed.includes(state)) {
+        fail(`invalid --state '${state}'`, `valid values: ${allowed.join(", ")}`, EXIT.USAGE);
+    }
+    const client = getClient();
+    let result;
+    try {
+        result = await client.listPullRequests(ref.projectKey, ref.repoSlug, state);
+    }
+    catch (err) {
+        bail(err, { ref });
+    }
+    const repo = `${ref.projectKey}/${ref.repoSlug}`;
+    if (result.values.length === 0) {
+        emit({ repo, state, pullRequests: [] });
+        emitRaw(`pullRequests: 0 ${state.toLowerCase()} pull requests in ${repo}`);
+        return;
+    }
+    const cols = resolveColumns(PR_FIELDS, PR_FIELDS_DEFAULT, fieldList(parsed), `${BIN} prs`);
+    emit({
+        repo,
+        state,
+        count: result.values.length,
+        complete: result.isLastPage,
+        pullRequests: result.values.map(pr => pick({
+            id: pr.id,
+            title: pr.title,
+            author: pr.author,
+            reviews: reviewerSummary(pr.reviewers),
+            from: pr.fromBranch,
+            to: pr.toBranch,
+            updated: pr.updatedDate,
+            url: pr.link ?? "",
+        }, cols)),
+        help: [
+            `Run \`${BIN} pr ${repo} <id>\` for a PR's details`,
+            `Run \`${BIN} diff ${repo} <id>\` to review its changes`,
+            ...(cols.length === PR_FIELDS_DEFAULT.length ? [`Run with \`--fields from,to,url\` for more columns`] : []),
+        ],
+    });
+}
+async function cmdPr(parsed) {
+    const ref = parseRepoRef(parsed.positionals[0], `${BIN} pr PROJECT/repo <id>`);
+    const prId = requireInt(parsed.positionals[1], "PR id", `${BIN} pr PROJECT/repo <id>`);
+    const client = getClient();
+    let pr;
+    try {
+        pr = await client.getPullRequest(ref.projectKey, ref.repoSlug, prId);
+    }
+    catch (err) {
+        bail(err, { ref, prId });
+    }
+    const repo = `${ref.projectKey}/${ref.repoSlug}`;
+    const doc = {
+        repo,
+        id: pr.id,
+        title: pr.title,
+        state: pr.state,
+        author: pr.author,
+        from: pr.fromBranch,
+        to: pr.toBranch,
+        version: pr.version,
+        updated: pr.updatedDate,
+        url: pr.link,
+    };
+    if (pr.reviewers.length > 0) {
+        doc.reviewers = pr.reviewers.map(r => ({ user: r.user, status: r.status }));
+    }
+    if (pr.description) {
+        const { text, truncated, total } = truncate(pr.description.trim(), DESC_TRUNCATE);
+        doc.description = truncated ? `${text} … (truncated, ${total} chars)` : text;
+    }
+    // Detail view is self-contained — no help block (§9).
+    emit(doc);
+}
+async function cmdDiff(parsed) {
+    const ref = parseRepoRef(parsed.positionals[0], `${BIN} diff PROJECT/repo <id>`);
+    const prId = requireInt(parsed.positionals[1], "PR id", `${BIN} diff PROJECT/repo <id>`);
+    const context = flagInt(parsed, "--context");
+    const full = flagBool(parsed, "--full");
+    const client = getClient();
+    let diff;
+    try {
+        diff = await client.getPrDiff(ref.projectKey, ref.repoSlug, prId, context);
+    }
+    catch (err) {
+        bail(err, { ref, prId });
+    }
+    const allLines = diff.replace(/\s+$/, "").split(/\r?\n/);
+    const total = allLines.length;
+    let shown = allLines;
+    let truncated = false;
+    if (!full && total > DIFF_LINES_DEFAULT) {
+        shown = allLines.slice(0, DIFF_LINES_DEFAULT);
+        truncated = true;
+    }
+    emit({
+        repo: `${ref.projectKey}/${ref.repoSlug}`,
+        pr: prId,
+        lines: truncated ? `${shown.length} of ${total} (head)` : `${total}`,
+    });
+    emitRaw("");
+    emitRaw(shown.join("\n"));
+    if (truncated) {
+        emitRaw("");
+        emit({ help: [`Run \`${BIN} diff ${ref.projectKey}/${ref.repoSlug} ${prId} --full\` for the complete diff`] });
+    }
+}
+async function cmdCreatePr(parsed) {
+    const ref = parseRepoRef(parsed.positionals[0], `${BIN} create-pr PROJECT/repo --title … --from … --to …`);
+    const title = flagStr(parsed, "--title");
+    const from = flagStr(parsed, "--from");
+    const to = flagStr(parsed, "--to");
+    const missing = [
+        !title && "--title",
+        !from && "--from",
+        !to && "--to",
+    ].filter(Boolean);
+    if (missing.length > 0) {
+        fail(`missing required flag(s): ${missing.join(", ")}`, `${BIN} create-pr ${ref.projectKey}/${ref.repoSlug} --title "<t>" --from <branch> --to <branch> [--reviewer <slug>]`, EXIT.USAGE);
+    }
+    const client = getClient();
+    let pr;
+    try {
+        pr = await client.createPullRequest(ref.projectKey, ref.repoSlug, title, from, to, flagStr(parsed, "--description"), flagList(parsed, "--reviewer"));
+    }
+    catch (err) {
+        bail(err, { ref });
+    }
+    emit({
+        created: `${ref.projectKey}/${ref.repoSlug} #${pr.id}`,
+        title: pr.title,
+        from: pr.fromBranch,
+        to: pr.toBranch,
+        url: pr.link,
+        help: [`Run \`${BIN} pr ${ref.projectKey}/${ref.repoSlug} ${pr.id}\` to view it`],
+    });
+}
+async function cmdMerge(parsed) {
+    const ref = parseRepoRef(parsed.positionals[0], `${BIN} merge PROJECT/repo <id>`);
+    const prId = requireInt(parsed.positionals[1], "PR id", `${BIN} merge PROJECT/repo <id>`);
+    let version = flagInt(parsed, "--version");
+    const client = getClient();
+    try {
+        // Version drives optimistic locking. If omitted, resolve the current one so
+        // the agent doesn't need a separate `pr` call first (AXI: avoid follow-ups).
+        // Fetching also lets us treat an already-merged PR as a no-op (§6).
+        if (version === undefined) {
+            const current = await client.getPullRequest(ref.projectKey, ref.repoSlug, prId);
+            if (current.state === "MERGED") {
+                emit({ merged: `${ref.projectKey}/${ref.repoSlug} #${prId}`, state: "MERGED", note: "already merged (no-op)" });
+                return; // exit 0 — desired state already holds
+            }
+            version = current.version;
+        }
+        const pr = await client.mergePullRequest(ref.projectKey, ref.repoSlug, prId, version);
+        emit({
+            merged: `${ref.projectKey}/${ref.repoSlug} #${prId}`,
+            title: pr.title,
+            state: pr.state,
+            into: pr.toBranch,
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (/conflict|409|not mergeable|declined|version/i.test(msg)) {
+            fail(msg.replace(/^Bitbucket API error \(\d+\):\s*/, ""), `Run \`${BIN} pr ${ref.projectKey}/${ref.repoSlug} ${prId}\` to check its state and current version`);
+        }
+        bail(err, { ref, prId });
+    }
+}
+async function cmdComment(parsed) {
+    const ref = parseRepoRef(parsed.positionals[0], `${BIN} comment PROJECT/repo <id> --text …`);
+    const prId = requireInt(parsed.positionals[1], "PR id", `${BIN} comment PROJECT/repo <id> --text …`);
+    const text = flagStr(parsed, "--text");
+    if (!text)
+        fail("--text is required", `${BIN} comment ${ref.projectKey}/${ref.repoSlug} ${prId} --text "<msg>"`, EXIT.USAGE);
+    const filePath = flagStr(parsed, "--file");
+    const line = flagInt(parsed, "--line");
+    if (line !== undefined && !filePath) {
+        fail("--line requires --file", `${BIN} comment … --file <path> --line <n>`, EXIT.USAGE);
+    }
+    const lineType = flagStr(parsed, "--line-type");
+    const fileType = flagStr(parsed, "--file-type");
+    const client = getClient();
+    let comment;
+    try {
+        comment = await client.addPrComment(ref.projectKey, ref.repoSlug, prId, { text, filePath, line, lineType, fileType });
+    }
+    catch (err) {
+        bail(err, { ref, prId });
+    }
+    emit({
+        commented: `${ref.projectKey}/${ref.repoSlug} #${prId}`,
+        commentId: comment.id,
+        inline: filePath ? `${filePath}${line !== undefined ? `:${line}` : ""}` : undefined,
+    });
+}
+// ─── Ambient (SessionStart) ─────────────────────────────────────────
+/**
+ * Ambient session-start snapshot (AXI §7): your open PRs. Runs on every
+ * session, so it is minimal and NEVER fails loudly — on missing creds or a
+ * slow/unreachable server it prints nothing and exits 0.
+ */
+async function cmdAmbient() {
+    const creds = loadCreds("bitbucket");
+    const baseUrl = getServiceBaseUrl("bitbucket", creds?.url);
+    if (!creds?.username || !creds?.password || !baseUrl)
+        return;
+    let prs;
+    try {
+        const client = new BitbucketClient(baseUrl, creds.username, creds.password);
+        ({ values: prs } = await withTimeout(client.dashboardPullRequests({ state: "OPEN" }), 2500));
+    }
+    catch {
+        return;
+    }
+    if (prs.length === 0)
+        return; // nothing actionable — stay quiet
+    const bin = binPath();
+    emitRaw(`oasis-bitbucket CLI ready — invoke: ${bin} (append \`help\` for all commands)`);
+    emit({
+        openPrs: prs.length,
+        prs: prs.slice(0, 15).map(pr => ({ id: pr.id, repo: repoFromLink(pr.link), title: pr.title, reviews: reviewerSummary(pr.reviewers) })),
+        help: [
+            `Run \`${bin} pr <project>/<repo> <id>\` to see a PR`,
+            `Run \`${bin} diff <project>/<repo> <id>\` to review its changes`,
+        ],
+    });
+}
+// ─── Help ───────────────────────────────────────────────────────────
+const HELP = {
+    auth: [
+        `${BIN} auth — configure Bitbucket credentials (stored in ~/.oasis.json, verified first)`,
+        "",
+        "flags:",
+        "  --user <u>       username",
+        "  --password <p>   password",
+        "  --clear          remove stored credentials",
+        "",
+        "with no flags: print current auth status",
+        "",
+        "examples:",
+        `  ${BIN} auth`,
+        `  ${BIN} auth --user alsaheb --password <pw>`,
+        `  ${BIN} auth --clear`,
+    ].join("\n"),
+    repos: [
+        `${BIN} repos <PROJECT> — list repositories in a project`,
+        "",
+        "flags:",
+        "  --fields <l>   add columns (available: slug,name,state,cloneUrl; default: slug,name,state)",
+        "",
+        "examples:",
+        `  ${BIN} repos OCL`,
+        `  ${BIN} repos OCL --fields cloneUrl`,
+    ].join("\n"),
+    branches: [
+        `${BIN} branches <PROJECT/repo> — list branches`,
+        "",
+        "examples:",
+        `  ${BIN} branches OCL/common-web-components`,
+    ].join("\n"),
+    prs: [
+        `${BIN} prs <PROJECT/repo> — list pull requests`,
+        "",
+        "flags:",
+        "  --state <s>    OPEN (default) | MERGED | DECLINED | ALL",
+        "  --fields <l>   add columns (available: id,title,author,reviews,from,to,updated,url; default: id,title,author,reviews)",
+        "",
+        "examples:",
+        `  ${BIN} prs OCL/common-web-components`,
+        `  ${BIN} prs OCL/common-web-components --state MERGED --fields from,to`,
+    ].join("\n"),
+    pr: [
+        `${BIN} pr <PROJECT/repo> <id> — PR details, reviewers, and version (for merge)`,
+        "",
+        "examples:",
+        `  ${BIN} pr OCL/common-web-components 671`,
+    ].join("\n"),
+    diff: [
+        `${BIN} diff <PROJECT/repo> <id> — unified diff (first ${DIFF_LINES_DEFAULT} lines by default)`,
+        "",
+        "flags:",
+        "  --context <n>   context lines around each change",
+        "  --full          print the entire diff",
+        "",
+        "examples:",
+        `  ${BIN} diff OCL/common-web-components 671`,
+    ].join("\n"),
+    "create-pr": [
+        `${BIN} create-pr <PROJECT/repo> — open a pull request (source branch must be pushed)`,
+        "",
+        "flags:",
+        "  --title <t>         required",
+        "  --from <branch>     required, source branch",
+        "  --to <branch>       required, target branch",
+        "  --description <d>   optional, markdown",
+        "  --reviewer <slug>   optional, repeatable",
+        "",
+        "examples:",
+        `  ${BIN} create-pr OCL/common-web-components --title "Fix X" --from feature/x --to master --reviewer alsaheb`,
+    ].join("\n"),
+    merge: [
+        `${BIN} merge <PROJECT/repo> <id> — merge an open PR (destructive)`,
+        "",
+        "flags:",
+        "  --version <n>   optimistic-lock version; auto-resolved from the PR if omitted",
+        "",
+        "examples:",
+        `  ${BIN} merge OCL/common-web-components 671`,
+    ].join("\n"),
+    comment: [
+        `${BIN} comment <PROJECT/repo> <id> — add a PR comment (general or inline)`,
+        "",
+        "flags:",
+        "  --text <msg>       required, markdown",
+        "  --file <path>      file path for an inline comment",
+        "  --line <n>         line number (requires --file)",
+        "  --line-type <t>    ADDED (default) | REMOVED | CONTEXT",
+        "  --file-type <t>    TO (default) | FROM",
+        "",
+        "examples:",
+        `  ${BIN} comment OCL/common-web-components 671 --text "LGTM"`,
+        `  ${BIN} comment OCL/common-web-components 671 --text "typo" --file src/a.ts --line 42`,
+    ].join("\n"),
+};
+const SKILL_SPEC = {
+    name: "bitbucket-cli",
+    binName: BIN,
+    description: "Browse Oasis Bitbucket (git server) and manage pull requests from the shell — list repos/branches/PRs, read a PR's details and reviewers, review its diff, create a PR, add comments, and merge. Use when the user asks about Bitbucket repos, branches, pull requests, PR reviews, diffs, or wants to open/comment on/merge a PR on the Oasis git server.",
+    intro: `Shell CLI for the Oasis Bitbucket Server (git + pull requests). Auth: \`${BIN} auth --user <u> --password <p>\`.`,
+    extra: [
+        "## Repo references",
+        "",
+        "Repos are addressed as `PROJECT/repo` (project key + repository slug), e.g.",
+        "`OAS_PLS/oasis-common`. `PROJECT` alone addresses a project.",
+    ],
+    commands: [
+        { cmd: "(no args)", summary: "live view: your open pull requests (author or reviewer)" },
+        { cmd: "repos <PROJECT> [--fields <l>]", summary: "list repositories in a project" },
+        { cmd: "branches <PROJECT/repo>", summary: "list branches (marks the default)" },
+        { cmd: "prs <PROJECT/repo> [--state <s>] [--fields <l>]", summary: "list pull requests (default OPEN)" },
+        { cmd: "pr <PROJECT/repo> <id>", summary: "PR details, reviewers, and version (needed to merge)" },
+        { cmd: "diff <PROJECT/repo> <id> [--context <n>] [--full]", summary: "unified diff — first 400 lines by default" },
+        { cmd: "create-pr <PROJECT/repo> --title <t> --from <b> --to <b> [--reviewer <s>]...", summary: "open a PR (source branch must be pushed)" },
+        { cmd: "comment <PROJECT/repo> <id> --text <m> [--file <p> --line <n>]", summary: "add a general or inline PR comment" },
+        { cmd: "merge <PROJECT/repo> <id> [--version <n>]", summary: "merge an open PR (version auto-resolved if omitted)" },
+        { cmd: "auth [--user <u> --password <p>]", summary: "configure credentials (no flags = status; --clear = sign out)" },
+    ],
+    examples: [
+        "# Review workflow for a PR",
+        `${BIN} pr   OAS_PLS/oasis-common 681`,
+        `${BIN} diff OAS_PLS/oasis-common 681`,
+        `${BIN} comment OAS_PLS/oasis-common 681 --text "LGTM"`,
+        "",
+        "# Open a PR",
+        `${BIN} create-pr OAS_PLS/oasis-common --title "Fix X" --from feature/x --to master --reviewer alsaheb`,
+        "",
+        "# Merge (version fetched automatically)",
+        `${BIN} merge OAS_PLS/oasis-common 681`,
+    ],
+    notes: [
+        "`merge` is destructive; version auto-resolves if omitted; already-merged is a no-op.",
+        "`reviews` = approval count (e.g. `2/3 approved`). Diffs truncated to 400 lines (`--full`).",
+        "Lists default to a minimal schema; `--fields` adds columns.",
+    ],
+};
+function topHelp() {
+    return [
+        `${BIN} — ${DESCRIPTION}`,
+        `bin: ${binPath()}`,
+        "",
+        "commands:",
+        "  (no args)                    live view: your open pull requests",
+        "  repos <PROJECT>              list repositories in a project",
+        "  branches <PROJECT/repo>      list branches",
+        "  prs <PROJECT/repo>           list pull requests (--state)",
+        "  pr <PROJECT/repo> <id>       PR details + version",
+        "  diff <PROJECT/repo> <id>     unified diff (head by default)",
+        "  create-pr <PROJECT/repo>     open a PR (--title --from --to)",
+        "  merge <PROJECT/repo> <id>    merge a PR",
+        "  comment <PROJECT/repo> <id>  add a PR comment (--text)",
+        "  auth                         configure credentials (--user --password)",
+        "  setup                        register ambient context for Codex + OpenCode",
+        "",
+        `Run \`${BIN} <command> --help\` for flags and examples.`,
+    ].join("\n");
+}
+// ─── Dispatch ───────────────────────────────────────────────────────
+const COMMAND_FLAGS = {
+    repos: { "--fields": "multi" },
+    branches: {},
+    prs: { "--state": "value", "--fields": "multi" },
+    pr: {},
+    diff: { "--context": "value", "--full": "bool" },
+    "create-pr": { "--title": "value", "--from": "value", "--to": "value", "--description": "value", "--reviewer": "multi" },
+    merge: { "--version": "value" },
+    comment: { "--text": "value", "--file": "value", "--line": "value", "--line-type": "value", "--file-type": "value" },
+};
+export async function main() {
+    const [, , command, ...rest] = process.argv;
+    if (command === "--ambient") {
+        await cmdAmbient().catch(() => { });
+        return;
+    }
+    if (command === "--skill-doc") {
+        emitRaw(renderSkillDoc(SKILL_SPEC));
+        return;
+    }
+    if (command === "setup") {
+        runSetup(BIN);
+        return;
+    }
+    if (command === "auth") {
+        if (rest.includes("--help")) {
+            emitRaw(HELP.auth);
+            return;
+        }
+        const parsed = parseArgs(rest, { "--user": "value", "--password": "value", "--clear": "bool" }, `${BIN} auth`);
+        await runAuth("bitbucket", parsed, {
+            binName: BIN,
+            label: "Bitbucket",
+            verify: async (c) => { await new BitbucketClient(getServiceBaseUrl("bitbucket", c.url), c.username, c.password).getUser(c.username); },
+        });
+        return;
+    }
+    if (command === undefined) {
+        await cmdHome();
+        return;
+    }
+    if (command === "help" || command === "--help" || command === "-h") {
+        const topic = rest[0];
+        emitRaw(topic && HELP[topic] ? HELP[topic] : topHelp());
+        return;
+    }
+    if (!(command in COMMAND_FLAGS)) {
+        fail(`unknown command '${command}'`, `valid commands: ${Object.keys(COMMAND_FLAGS).join(", ")} (run \`${BIN} help\`)`, EXIT.USAGE);
+    }
+    const known = COMMAND_FLAGS[command];
+    const parsed = parseArgs(rest, known, `${BIN} ${command}`);
+    if (flagBool(parsed, "--help")) {
+        emitRaw(HELP[command] ?? topHelp());
+        return;
+    }
+    switch (command) {
+        case "repos": return cmdRepos(parsed);
+        case "branches": return cmdBranches(parsed);
+        case "prs": return cmdPrs(parsed);
+        case "pr": return cmdPr(parsed);
+        case "diff": return cmdDiff(parsed);
+        case "create-pr": return cmdCreatePr(parsed);
+        case "merge": return cmdMerge(parsed);
+        case "comment": return cmdComment(parsed);
+    }
+}
+/** Entry used by bin/: run main() and convert any escaped error into an AXI error (§6). */
+export function run() {
+    main().catch(err => {
+        fail(err instanceof Error ? err.message : String(err));
+    });
+}
+/** Single source of truth for skills/bitbucket-cli/SKILL.md (§7). */
+export function skillMarkdown() {
+    return renderSkillDoc(SKILL_SPEC);
+}
+//# sourceMappingURL=cli.js.map