promigence 0.1.0-beta.12

package/dist/github.js

@@ -0,0 +1,307 @@
+import { PromigenceError, parseGithubRepo, parseGitlabRepo, validGitRef, GITLAB_REPO_PREFIX, } from "./sdk/index.js";
+import { bool, client, list, nexts, positional, str } from "./commands.js";
+import { buildPrice } from "./pricing.js";
+import { emit, okEnvelope, parseCount, parseDuration, usageError, write } from "./io.js";
+import { headless, openBrowser } from "./login.js";
+import { jsonLine, sh } from "./term.js";
+import { gitlabRepos } from "./gitlab.js";
+import { consoleConnect, consoleTicket } from "./connectreq.js";
+export const CONNECT_WAIT_DEFAULT = "10m";
+const POLL_MS_DEFAULT = 2000;
+function pollMs() {
+    const v = Number(process.env["PROMIGENCE_GITHUB_POLL_MS"]);
+    return Number.isFinite(v) && v > 0 ? v : POLL_MS_DEFAULT;
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function notConfigured(s) {
+    return usageError(s.message ?? "Connecting GitHub isn't available here yet", "Bring the code in another way: `promigence snapshot create --dir .` uploads the files git tracks here, or clone a public repository in a --setup step.");
+}
+function connectionLine(c) {
+    return `  ${c.account}  ${c.account_type} · ${c.repository_selection} repositories · installation ${c.installation_id}${c.suspended ? "  SUSPENDED on GitHub" : ""}`;
+}
+function trackLine(t) {
+    const state = t.build_id
+        ? `building ${t.build_id}`
+        : t.built_sha
+            ? `built ${t.built_sha.slice(0, 7)}${t.snapshot_id ? ` (${t.snapshot_id})` : ""}`
+            : "not built yet";
+    return `  ${t.track_id}  ${t.repo}:${t.branch} -> ${t.alias}  ${state}${t.last_error ? `  last error: ${t.last_error}` : ""}`;
+}
+const githubConnect = async (ctx) => {
+    const bound = parseDuration(str(ctx, "--wait-timeout") ?? CONNECT_WAIT_DEFAULT, "--wait-timeout");
+    const c = client(ctx);
+    const before = await c.github.status();
+    if (!before.configured)
+        throw notConfigured(before);
+    const ticket = await consoleTicket(() => c.github.ticket());
+    if (ticket) {
+        return consoleConnect(ctx, "github", {
+            ticket,
+            poll: () => c.github.request(ticket.request_id),
+            connections: async (r) => (await c.github.status()).connections.filter((x) => x.account === r.account),
+            bound,
+            waitText: str(ctx, "--wait-timeout") ?? CONNECT_WAIT_DEFAULT,
+            pollMs: pollMs(),
+            okNext: [
+                ["promigence repos", "the repositories the connection can read"],
+                ["promigence snapshot create --repo <owner>/<repo> --ref main --alias app --wait", "build a snapshot from one"],
+            ],
+        });
+    }
+    const known = new Set(before.connections.map((x) => `${x.installation_id}@${x.connected_at}`));
+    const link = await c.github.connect();
+    const opened = bool(ctx, "--no-open") || headless() ? false : openBrowser(link.install_url);
+    const noWait = bool(ctx, "--no-wait");
+    if (ctx.mode === "json") {
+        await write(process.stderr, jsonLine(process.stderr, {
+            hint: "install_url", install_url: link.install_url, expires_at: link.expires_at, opened,
+        }));
+    }
+    else {
+        await write(process.stderr, [
+            opened
+                ? "Opening GitHub to install the App on your account; then confirm by signing in to Promigence in the same browser…"
+                : "Open this link to install the App on your GitHub account, then confirm by signing in to Promigence in the same browser:",
+            `  ${opened ? "If it did not open: " : ""}${link.install_url}`,
+            "  Choose the account, and all repositories or only the ones you pick. The link works for 15 minutes, for whoever opens it: keep it to yourself.",
+            ...(noWait ? [] : [`  Waiting up to ${str(ctx, "--wait-timeout") ?? CONNECT_WAIT_DEFAULT} for GitHub (Ctrl-C stops waiting; the install still completes).`]),
+        ].join("\n") + "\n");
+    }
+    if (noWait) {
+        const next = nexts(["promigence github status", "after the install: the connected account"]);
+        return emit(ctx.mode, okEnvelope(ctx.cmd.name, {
+            install_url: link.install_url, expires_at: link.expires_at, opened, waited: false, connected: [],
+        }, next), [`install link: ${link.install_url}`, `  next: ${next[0].cmd}`], 0, ctx.pointer);
+    }
+    const t0 = Date.now();
+    let saidPending = false;
+    for (;;) {
+        await sleep(Math.min(pollMs(), Math.max(0, bound - (Date.now() - t0))));
+        const now = await c.github.status();
+        const fresh = now.connections.filter((x) => !known.has(`${x.installation_id}@${x.connected_at}`));
+        if (fresh.length) {
+            const next = nexts(["promigence repos", "the repositories the connection can read"], [sh `promigence snapshot create --repo ${`${fresh[0].account}/<repo>`} --ref main --alias app --wait`, "build a snapshot from one"]);
+            return emit(ctx.mode, okEnvelope(ctx.cmd.name, {
+                install_url: link.install_url, opened, waited: true, waited_ms: Date.now() - t0, connected: fresh,
+            }, next), [
+                `connected: ${fresh.map((x) => x.account).join(", ")}`,
+                ...fresh.map(connectionLine),
+                `  next: ${next[0].cmd}`,
+            ], 0, ctx.pointer);
+        }
+        if (!saidPending && now.pending.length && ctx.mode !== "json") {
+            saidPending = true;
+            await write(process.stderr, "  GitHub has not confirmed the install to us yet; still waiting…\n");
+        }
+        if (Date.now() - t0 >= bound) {
+            throw new PromigenceError({
+                code: "timeout",
+                message: `no new GitHub connection within ${str(ctx, "--wait-timeout") ?? CONNECT_WAIT_DEFAULT}`,
+                fix: `Finish the install in the browser (the link works until ${link.expires_at}), then \`promigence github status\`; or run \`promigence github connect\` again for a new link. If you only changed which repositories an existing connection can read, that already took effect: \`promigence repos\`.`,
+                exitCode: 11,
+            });
+        }
+    }
+};
+const githubStatus = async (ctx) => {
+    const s = await client(ctx).github.status();
+    if (!s.configured) {
+        const next = nexts(["promigence snapshot create --dir . --alias app --wait", "bring the files git tracks here instead"]);
+        return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...s }, next), [`github: ${s.message ?? "Connecting GitHub isn't available here yet"}`], 0, ctx.pointer);
+    }
+    const lines = [
+        s.connections.length
+            ? `github: connected to ${s.connections.length} account${s.connections.length === 1 ? "" : "s"}`
+            : "github: not connected",
+        ...s.connections.map(connectionLine),
+    ];
+    if (s.pending.length) {
+        lines.push("pending:", ...s.pending.map((p) => `  installation ${p.installation_id}${p.account ? ` (${p.account})` : ""}: ${p.message}`));
+    }
+    if (s.tracks.length)
+        lines.push("tracked branches (each push rebuilds, billed per second):", ...s.tracks.map(trackLine));
+    const next = s.connections.length
+        ? nexts(["promigence repos", "the repositories the connection can read"])
+        : nexts(["promigence github connect", "install the App on your GitHub account"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...s }, next), lines, 0, ctx.pointer);
+};
+function notFound(message, fix) {
+    return new PromigenceError({ code: "not_found", message, fix, exitCode: 8 });
+}
+const githubDisconnect = async (ctx) => {
+    const arg = positional(ctx, "an installation id or a GitHub account", "promigence github disconnect acme");
+    const c = client(ctx);
+    let id = arg;
+    if (!/^\d+$/.test(arg)) {
+        const s = await c.github.status();
+        if (!s.configured)
+            throw notConfigured(s);
+        const hits = s.connections.filter((x) => x.account.toLowerCase() === arg.toLowerCase());
+        if (hits.length !== 1) {
+            throw notFound(`no GitHub connection for the account ${JSON.stringify(arg)}`, `\`promigence github status\` lists the connected accounts${s.connections.length ? ` (${s.connections.map((x) => x.account).join(", ")})` : ""}; pass the account or its installation id.`);
+        }
+        id = String(hits[0].installation_id);
+    }
+    const d = await c.github.disconnect(id);
+    const next = nexts(["promigence github status", "what is still connected"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...d }, next), [
+        `disconnected: ${d.account} (installation ${d.installation_id})${d.tracks_removed ? `; ${d.tracks_removed} tracked branch${d.tracks_removed === 1 ? "" : "es"} stopped` : ""}`,
+        `  The App stays installed on GitHub until you uninstall it there: ${d.uninstall_url}`,
+    ], 0, ctx.pointer);
+};
+const githubUntrack = async (ctx) => {
+    const arg = positional(ctx, "a track id or the alias it moves", "promigence github untrack app-main");
+    const c = client(ctx);
+    let id = arg;
+    if (!arg.startsWith("trk_")) {
+        const s = await c.github.status();
+        if (!s.configured)
+            throw notConfigured(s);
+        const hits = s.tracks.filter((t) => t.alias === arg);
+        if (hits.length !== 1) {
+            throw notFound(`no tracked branch moves the alias ${JSON.stringify(arg)}`, "`promigence github status` lists the tracked branches; pass the alias or the trk_ id.");
+        }
+        id = hits[0].track_id;
+    }
+    const u = await c.github.untrack(id);
+    const next = nexts(["promigence github status", "the branches still tracked"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...u }, next), [
+        `untracked: ${u.repo}:${u.branch} no longer rebuilds ${u.alias} on a push; the snapshot itself stays`,
+    ], 0, ctx.pointer);
+};
+const repos = async (ctx) => {
+    const provider = str(ctx, "--provider") ?? "github";
+    if (provider === "gitlab")
+        return gitlabRepos(ctx);
+    if (provider !== "github") {
+        throw usageError(`--provider must be github or gitlab, got ${JSON.stringify(provider)}`, "Pass --provider gitlab for GitLab projects; GitHub is the default.");
+    }
+    if (str(ctx, "--connection") !== undefined) {
+        throw usageError("--connection is for --provider gitlab", "Drop it, or add --provider gitlab.");
+    }
+    const pageArg = str(ctx, "--page");
+    const page = pageArg === undefined ? 1 : parseCount(pageArg, "--page");
+    const c = client(ctx);
+    const r = await c.github.repos({ page });
+    if (r.total === 0 && r.repos.length === 0) {
+        const s = await c.github.status().catch(() => undefined);
+        if (s && !s.configured)
+            throw notConfigured(s);
+        const next = nexts(["promigence github connect", "install the App on your GitHub account"]);
+        return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...r }, next), [
+            s?.connections.length
+                ? "repos: none — the connection can read no repository; give the App access to some on GitHub"
+                : "repos: none — connect GitHub first",
+            `  next: ${next[0].cmd}`,
+        ], 0, ctx.pointer);
+    }
+    const width = Math.min(48, Math.max(...r.repos.map((x) => x.full_name.length), 10));
+    const lines = [
+        `repos: ${r.total}${r.has_more || page > 1 ? ` (page ${r.page})` : ""}`,
+        ...r.repos.map((x) => `  ${x.full_name.padEnd(width)}  ${x.private ? "private" : "public "}  ${x.default_branch}${x.archived ? "  archived" : ""}`),
+    ];
+    if (r.has_more)
+        lines.push(`  more: ${sh `promigence repos --page ${r.page + 1}`}`);
+    const first = r.repos[0];
+    const next = first
+        ? nexts([sh `promigence snapshot create --repo ${first.full_name} --ref ${first.default_branch} --alias app --wait`, "build a snapshot from it"])
+        : nexts(["promigence repos --page 1", "the first page"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...r }, next), lines, 0, ctx.pointer);
+};
+const NOT_WITH_GITHUB = [
+    ["--image", "the build starts from a snapshot: build the image first (`snapshot create --image REF --alias base`), then pass --from base"],
+    ["--dockerfile", "the build starts from a snapshot: build the Dockerfile first, then pass --from <its alias>"],
+    ["--context", "it belongs to --dockerfile"],
+    ["--devcontainer", "it is not read for a connected repository; use --setup steps"],
+    ["--start", "a background process is part of an image snapshot"],
+    ["--also-repo", "clone further repositories in a --setup step"],
+    ["--dir", "--dir uploads a local tree instead; pass one of them"],
+];
+const GITHUB_ONLY = ["--ref", "--from", "--track"];
+export async function githubCreate(ctx) {
+    const repoArg = str(ctx, "--repo");
+    const isGitlab = typeof repoArg === "string" && repoArg.trim().startsWith(GITLAB_REPO_PREFIX);
+    const glPath = isGitlab ? parseGitlabRepo(repoArg) : undefined;
+    if (isGitlab && !glPath) {
+        throw usageError(`--repo ${JSON.stringify(repoArg)} is not a GitLab project path`, "Pass --repo gitlab:group/project (see `promigence repos --provider gitlab`).");
+    }
+    const gh = glPath ? { owner: "", name: "" } : parseGithubRepo(repoArg);
+    const shown = glPath ? `gitlab:${glPath}` : gh ? `${gh.owner}/${gh.name}` : "";
+    if (!gh) {
+        const stray = GITHUB_ONLY.find((f) => bool(ctx, f));
+        if (stray) {
+            throw usageError(`${stray} is for a connected GitHub repository (--repo owner/name)`, "Pass --repo your-org/app (see `promigence repos`), or drop it: a git URL is built at --commit SHA.");
+        }
+        return undefined;
+    }
+    for (const [flag, why] of NOT_WITH_GITHUB) {
+        if (bool(ctx, flag))
+            throw usageError(`${flag} is not taken with --repo ${shown}`, `Drop ${flag}: ${why}.`);
+    }
+    const ref = str(ctx, "--ref");
+    const commit = str(ctx, "--commit");
+    if (ref !== undefined && commit !== undefined) {
+        throw usageError("--ref and --commit name the same thing twice", "Pass one: a branch or tag as --ref, or a sha as --commit.");
+    }
+    if (ref !== undefined && !validGitRef(ref.trim())) {
+        throw usageError(`--ref must be a branch, a tag or a commit sha, got ${JSON.stringify(ref)}`, "Example: --ref main, --ref v1.2.0, or --ref $(git rev-parse HEAD).");
+    }
+    if (commit !== undefined && !/^[0-9a-f]{40}$/i.test(commit)) {
+        throw usageError(`--commit must be a full 40-character sha, got ${JSON.stringify(commit)}`, "Pass --commit $(git rev-parse HEAD), or a branch or tag as --ref.");
+    }
+    const track = bool(ctx, "--track");
+    const alias = str(ctx, "--alias");
+    if (track && alias === undefined) {
+        throw usageError("--track needs --alias", "Every push builds the snapshot again and moves the alias to it, so the alias is how you start the newest one: --alias app-main --track.");
+    }
+    if (track && commit !== undefined) {
+        throw usageError("--track follows a branch, not a commit", "Pass --ref <branch> --track (no --ref: the default branch).");
+    }
+    const repo = glPath ? `gitlab:${glPath}` : `github:${gh.owner}/${gh.name}`;
+    const from = str(ctx, "--from");
+    const setup = list(ctx, "--setup");
+    const verify = str(ctx, "--verify");
+    const tier = str(ctx, "--tier");
+    const opts = { repo };
+    if (ref !== undefined)
+        opts.ref = ref.trim();
+    if (commit !== undefined)
+        opts.commit = commit;
+    if (from !== undefined)
+        opts.from = from;
+    if (setup.length)
+        opts.setup = setup;
+    if (verify !== undefined)
+        opts.verify = { cmd: verify };
+    if (tier !== undefined)
+        opts.tier = tier;
+    if (track)
+        opts.track = true;
+    const at = ref ?? (commit ? commit.slice(0, 7) : undefined);
+    const label = at === undefined ? `${repo} (default branch)` : `${repo}@${at}`;
+    const submitted = {
+        build_price: null, repo,
+        ...(ref === undefined ? {} : { ref: ref.trim() }),
+        ...(commit === undefined ? {} : { commit: commit.toLowerCase() }),
+        ...(from === undefined ? {} : { from }),
+        ...(tier === undefined ? {} : { requested_tier: tier }),
+        ...(track ? { track: true } : {}),
+    };
+    if (track) {
+        const branch = ref ?? "the default branch";
+        const each = (await buildPrice(client(ctx), tier)).most_usd;
+        await write(process.stderr, ctx.mode === "json"
+            ? jsonLine(process.stderr, { hint: "track", repo, branch, alias, build_price_each: each, unit: "USD" })
+            : glPath
+                ? `tracking: every new commit on ${branch} (checked every minute) rebuilds this snapshot and moves ${alias} to it, each build billed per second while it runs (up to $${each.toFixed(2)}), charged to your org; stop with \`${sh `promigence gitlab untrack ${alias}`}\`\n`
+                : `tracking: every push to ${branch} rebuilds this snapshot and moves ${alias} to it, each build billed per second while it runs (up to $${each.toFixed(2)}), charged to your org; stop with \`${sh `promigence github untrack ${alias}`}\`\n`);
+    }
+    return { opts, label, submitted, tier };
+}
+export const GITHUB_HANDLERS = {
+    "github connect": githubConnect,
+    "github status": githubStatus,
+    "github disconnect": githubDisconnect,
+    "github untrack": githubUntrack,
+    repos,
+};

package/dist/gitlab.js

@@ -0,0 +1,210 @@
+import { PromigenceError, } from "./sdk/index.js";
+import { bool, client, nexts, positional, str } from "./commands.js";
+import { emit, okEnvelope, parseCount, parseDuration, usageError, write } from "./io.js";
+import { headless, openBrowser } from "./login.js";
+import { jsonLine, sh } from "./term.js";
+import { consoleConnect, consoleTicket } from "./connectreq.js";
+export const CONNECT_WAIT_DEFAULT = "10m";
+const POLL_MS_DEFAULT = 2000;
+function pollMs() {
+    const v = Number(process.env["PROMIGENCE_GITHUB_POLL_MS"]);
+    return Number.isFinite(v) && v > 0 ? v : POLL_MS_DEFAULT;
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function notConfigured(s) {
+    return usageError(s.message ?? "Connecting GitLab isn't available here yet", "Bring the code in another way: `promigence snapshot create --dir .` uploads the files git tracks here, or clone in a --setup step.");
+}
+function connectionLine(c) {
+    return `  ${c.username}  on ${c.gitlab_url} · ${c.connection_id}${c.broken ? `  BROKEN: ${c.broken_reason ?? "connect again"}` : ""}`;
+}
+function trackLine(t) {
+    const state = t.build_id
+        ? `building ${t.build_id}`
+        : t.built_sha
+            ? `built ${t.built_sha.slice(0, 7)}${t.snapshot_id ? ` (${t.snapshot_id})` : ""}`
+            : "not built yet";
+    return `  ${t.track_id}  ${t.repo}:${t.branch} -> ${t.alias}  ${state}${t.last_error ? `  last error: ${t.last_error}` : ""}`;
+}
+function notFound(message, fix) {
+    return new PromigenceError({ code: "not_found", message, fix, exitCode: 8 });
+}
+const gitlabConnect = async (ctx) => {
+    const bound = parseDuration(str(ctx, "--wait-timeout") ?? CONNECT_WAIT_DEFAULT, "--wait-timeout");
+    const c = client(ctx);
+    const before = await c.gitlab.status();
+    if (!before.configured)
+        throw notConfigured(before);
+    const ticket = await consoleTicket(() => c.gitlab.ticket());
+    if (ticket) {
+        return consoleConnect(ctx, "gitlab", {
+            ticket,
+            poll: () => c.gitlab.request(ticket.request_id),
+            connections: async (r) => (await c.gitlab.status()).connections.filter((x) => x.username === (r.account ?? "").split(" on ")[0]),
+            bound,
+            waitText: str(ctx, "--wait-timeout") ?? CONNECT_WAIT_DEFAULT,
+            pollMs: pollMs(),
+            okNext: [
+                ["promigence repos --provider gitlab", "the projects the connection can read"],
+                ["promigence snapshot create --repo gitlab:<group>/<project> --ref main --alias app --wait", "build a snapshot from one"],
+            ],
+        });
+    }
+    const known = new Set(before.connections.map((x) => x.connection_id));
+    const link = await c.gitlab.connect();
+    const opened = bool(ctx, "--no-open") || headless() ? false : openBrowser(link.authorize_url);
+    const noWait = bool(ctx, "--no-wait");
+    if (ctx.mode === "json") {
+        await write(process.stderr, jsonLine(process.stderr, {
+            hint: "authorize_url", authorize_url: link.authorize_url, expires_at: link.expires_at, opened, scopes: link.scopes,
+        }));
+    }
+    else {
+        await write(process.stderr, [
+            opened
+                ? `Opening ${link.gitlab_url} to authorize the Promigence application (read-only)…`
+                : `Open this link to authorize the Promigence application on ${link.gitlab_url} (read-only):`,
+            `  ${opened ? "If it did not open: " : ""}${link.authorize_url}`,
+            "  Then sign in to Promigence on the page it shows: an owner of this organization confirms the connection there. The link works for 15 minutes, for whoever opens it: keep it to yourself.",
+            ...(noWait ? [] : [`  Waiting up to ${str(ctx, "--wait-timeout") ?? CONNECT_WAIT_DEFAULT} (Ctrl-C stops waiting).`]),
+        ].join("\n") + "\n");
+    }
+    if (noWait) {
+        const next = nexts(["promigence gitlab status", "after the confirmation: the connection"]);
+        return emit(ctx.mode, okEnvelope(ctx.cmd.name, {
+            authorize_url: link.authorize_url, expires_at: link.expires_at, opened, waited: false, connected: [],
+        }, next), [`authorize link: ${link.authorize_url}`, `  next: ${next[0].cmd}`], 0, ctx.pointer);
+    }
+    const t0 = Date.now();
+    let saidPending = false;
+    for (;;) {
+        await sleep(Math.min(pollMs(), Math.max(0, bound - (Date.now() - t0))));
+        const now = await c.gitlab.status();
+        const fresh = now.connections.filter((x) => !known.has(x.connection_id));
+        if (fresh.length) {
+            const next = nexts(["promigence repos --provider gitlab", "the projects the connection can read"], [sh `promigence snapshot create --repo ${`gitlab:${fresh[0].username}/<project>`} --ref main --alias app --wait`, "build a snapshot from one"]);
+            return emit(ctx.mode, okEnvelope(ctx.cmd.name, {
+                authorize_url: link.authorize_url, opened, waited: true, waited_ms: Date.now() - t0, connected: fresh,
+            }, next), [
+                `connected: ${fresh.map((x) => x.username).join(", ")}`,
+                ...fresh.map(connectionLine),
+                `  next: ${next[0].cmd}`,
+            ], 0, ctx.pointer);
+        }
+        if (!saidPending && now.pending.length && ctx.mode !== "json") {
+            saidPending = true;
+            await write(process.stderr, "  Authorized on GitLab; waiting for an owner to confirm it in that browser…\n");
+        }
+        if (Date.now() - t0 >= bound) {
+            throw new PromigenceError({
+                code: "timeout",
+                message: `no new GitLab connection within ${str(ctx, "--wait-timeout") ?? CONNECT_WAIT_DEFAULT}`,
+                fix: `Finish in the browser (the link works until ${link.expires_at}): authorize on GitLab, then sign in to Promigence as an owner of this organization on the page that follows. Then \`promigence gitlab status\`; or run \`promigence gitlab connect\` again for a new link.`,
+                exitCode: 11,
+            });
+        }
+    }
+};
+const gitlabStatus = async (ctx) => {
+    const s = await client(ctx).gitlab.status();
+    if (!s.configured) {
+        const next = nexts(["promigence snapshot create --dir . --alias app --wait", "bring the files git tracks here instead"]);
+        return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...s }, next), [`gitlab: ${s.message ?? "Connecting GitLab isn't available here yet"}`], 0, ctx.pointer);
+    }
+    const lines = [
+        s.connections.length
+            ? `gitlab: connected to ${s.connections.length} GitLab user${s.connections.length === 1 ? "" : "s"}`
+            : "gitlab: not connected",
+        ...s.connections.map(connectionLine),
+    ];
+    if (s.pending.length) {
+        lines.push("waiting for an owner's confirmation:", ...s.pending.map((p) => `  ${p.username} (${p.connection_id}): ${p.message}`));
+    }
+    if (s.tracks.length) {
+        lines.push("tracked branches (each new commit rebuilds, billed per second; checked every minute):", ...s.tracks.map(trackLine));
+    }
+    if (s.connections.length) {
+        lines.push("optional, for instant rebuilds: a project webhook (push events) with each connection's URL and token in --json (webhook_url, webhook_token)");
+    }
+    const next = s.connections.length
+        ? nexts(["promigence repos --provider gitlab", "the projects the connection can read"])
+        : nexts(["promigence gitlab connect", "authorize the application on GitLab (read-only)"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...s }, next), lines, 0, ctx.pointer);
+};
+const gitlabDisconnect = async (ctx) => {
+    const arg = positional(ctx, "a connection id or a GitLab username", "promigence gitlab disconnect octo-dev");
+    const c = client(ctx);
+    let id = arg;
+    if (!arg.startsWith("glc_")) {
+        const s = await c.gitlab.status();
+        if (!s.configured)
+            throw notConfigured(s);
+        const hits = s.connections.filter((x) => x.username.toLowerCase() === arg.toLowerCase());
+        if (hits.length !== 1) {
+            throw notFound(`no GitLab connection for the user ${JSON.stringify(arg)}`, `\`promigence gitlab status\` lists the connections${s.connections.length ? ` (${s.connections.map((x) => x.username).join(", ")})` : ""}; pass the username or its glc_ id.`);
+        }
+        id = hits[0].connection_id;
+    }
+    const d = await c.gitlab.disconnect(id);
+    const next = nexts(["promigence gitlab status", "what is still connected"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...d }, next), [
+        `disconnected: ${d.username} (${d.connection_id})${d.tracks_removed ? `; ${d.tracks_removed} tracked branch${d.tracks_removed === 1 ? "" : "es"} stopped` : ""}`,
+        `  ${d.message}`,
+    ], 0, ctx.pointer);
+};
+const gitlabUntrack = async (ctx) => {
+    const arg = positional(ctx, "a track id or the alias it moves", "promigence gitlab untrack app-main");
+    const c = client(ctx);
+    let id = arg;
+    if (!arg.startsWith("trk_")) {
+        const s = await c.gitlab.status();
+        if (!s.configured)
+            throw notConfigured(s);
+        const hits = s.tracks.filter((t) => t.alias === arg);
+        if (hits.length !== 1) {
+            throw notFound(`no tracked GitLab branch moves the alias ${JSON.stringify(arg)}`, "`promigence gitlab status` lists the tracked branches; pass the alias or the trk_ id.");
+        }
+        id = hits[0].track_id;
+    }
+    const u = await c.gitlab.untrack(id);
+    const next = nexts(["promigence gitlab status", "the branches still tracked"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...u }, next), [
+        `untracked: ${u.repo}:${u.branch} no longer rebuilds ${u.alias} on a new commit; the snapshot itself stays`,
+    ], 0, ctx.pointer);
+};
+export const gitlabRepos = async (ctx) => {
+    const pageArg = str(ctx, "--page");
+    const page = pageArg === undefined ? 1 : parseCount(pageArg, "--page");
+    const c = client(ctx);
+    const connectionId = str(ctx, "--connection");
+    const r = await c.gitlab.repos({ page, ...(connectionId ? { connectionId } : {}) });
+    if (r.repos.length === 0 && page === 1) {
+        const s = await c.gitlab.status().catch(() => undefined);
+        if (s && !s.configured)
+            throw notConfigured(s);
+        const next = nexts(["promigence gitlab connect", "authorize the application on GitLab (read-only)"]);
+        return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...r }, next), [
+            s?.connections.length
+                ? "repos: none — the connected GitLab user is a member of no project they can read"
+                : "repos: none — connect GitLab first",
+            `  next: ${next[0].cmd}`,
+        ], 0, ctx.pointer);
+    }
+    const width = Math.min(56, Math.max(...r.repos.map((x) => x.path.length), 10));
+    const lines = [
+        `repos (gitlab): ${r.repos.length}${r.has_more || page > 1 ? ` (page ${r.page})` : ""}`,
+        ...r.repos.map((x) => `  ${x.path.padEnd(width)}  ${x.private ? "private" : "public "}  ${x.default_branch}${x.archived ? "  archived" : ""}`),
+    ];
+    if (r.has_more)
+        lines.push(`  more: ${sh `promigence repos --provider gitlab --page ${r.page + 1}`}`);
+    const first = r.repos[0];
+    const next = first
+        ? nexts([sh `promigence snapshot create --repo ${`gitlab:${first.path}`} --ref ${first.default_branch} --alias app --wait`, "build a snapshot from it"])
+        : nexts(["promigence repos --provider gitlab --page 1", "the first page"]);
+    return emit(ctx.mode, okEnvelope(ctx.cmd.name, { ...r }, next), lines, 0, ctx.pointer);
+};
+export const GITLAB_HANDLERS = {
+    "gitlab connect": gitlabConnect,
+    "gitlab status": gitlabStatus,
+    "gitlab disconnect": gitlabDisconnect,
+    "gitlab untrack": gitlabUntrack,
+};

package/dist/guide.d.ts

@@ -0,0 +1,19 @@
+import { type ErrorEntry } from "./generated.js";
+export declare const BILLED_TEXT: Readonly<Record<string, string>>;
+import type { Prices } from "./pricing.js";
+export type Section = "core" | "commands" | "errors" | "cost";
+export declare const SECTIONS: readonly Section[];
+export declare const BUDGETS: Readonly<Record<Section, number>>;
+export declare function lookupError(code: string): ErrorEntry | undefined;
+export declare const ALL_ERROR_CODES: readonly string[];
+export declare const estimateTokens: (s: string) => number;
+export declare const HUMAN_START = "promigence run --count 1 --cap 1 -- python3 -c 'print(6*7)'";
+export declare function humanHeader(): string;
+export interface GuideOpts {
+    section?: Section;
+    code?: string;
+    prices?: Prices;
+}
+export declare function renderGuide(opts?: GuideOpts): string;
+export declare function guideJson(opts?: GuideOpts): Record<string, unknown>;
+export declare function renderLlmsTxt(): string;