@promigence/sdk 0.1.0-beta.12

package/dist/cjs/credstore.js

@@ -0,0 +1,219 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KEYCHAIN_SERVICE = void 0;
+exports.storeLabel = storeLabel;
+exports.keychainStore = keychainStore;
+exports.keychainsToClear = keychainsToClear;
+exports.keychainRead = keychainRead;
+exports.keychainWrite = keychainWrite;
+exports.keychainDelete = keychainDelete;
+exports.encodeCredentials = encodeCredentials;
+exports.keychainReadCached = keychainReadCached;
+exports.keychainCacheSet = keychainCacheSet;
+exports.forgetKeychainReads = forgetKeychainReads;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+exports.KEYCHAIN_SERVICE = "promigence-cli";
+const KEYCHAIN_LABEL = "Promigence CLI credentials";
+function storeLabel(store, path) {
+    switch (store) {
+        case "macos-keychain": return "the macOS Keychain";
+        case "secret-service": return "the Secret Service keyring";
+        default: return path ? `the credentials file (${path})` : "the credentials file";
+    }
+}
+function onPath(name, env) {
+    for (const dir of (env["PATH"] ?? "").split(node_path_1.delimiter)) {
+        if (!dir)
+            continue;
+        const p = (0, node_path_1.join)(dir, name);
+        try {
+            (0, node_fs_1.accessSync)(p, node_fs_1.constants.X_OK);
+            return p;
+        }
+        catch { }
+    }
+    return undefined;
+}
+const toolName = (store) => (store === "macos-keychain" ? "security" : "secret-tool");
+function sessionBus(env) {
+    if (env["DBUS_SESSION_BUS_ADDRESS"])
+        return true;
+    const run = env["XDG_RUNTIME_DIR"];
+    return Boolean(run) && (0, node_fs_1.existsSync)((0, node_path_1.join)(run, "bus"));
+}
+function userHome(env, home = node_os_1.homedir) {
+    const h = env["HOME"];
+    if (h)
+        return h;
+    try {
+        return home() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const warnedSetting = new Set();
+function keychainStore(env = process.env, platform = process.platform, home = node_os_1.homedir) {
+    const raw = (env["PROMIGENCE_CREDENTIAL_STORE"] ?? "").trim().toLowerCase();
+    switch (raw) {
+        case "file": return undefined;
+        case "macos-keychain":
+        case "secret-service": return raw;
+        case "":
+        case "auto": break;
+        default:
+            if (!warnedSetting.has(raw)) {
+                warnedSetting.add(raw);
+                process.emitWarning(`PROMIGENCE_CREDENTIAL_STORE=${raw} is not one of auto, file, macos-keychain, secret-service; using auto`, { code: "PROMIGENCE_CREDENTIALS" });
+            }
+    }
+    if (platform === "darwin") {
+        const h = userHome(env, home);
+        return h && (0, node_fs_1.existsSync)((0, node_path_1.join)(h, "Library", "Keychains")) && onPath("security", env) ? "macos-keychain" : undefined;
+    }
+    if (platform === "win32")
+        return undefined;
+    return onPath("secret-tool", env) && sessionBus(env) ? "secret-service" : undefined;
+}
+function keychainsToClear(env = process.env, platform = process.platform) {
+    const out = new Set();
+    const chosen = keychainStore(env, platform);
+    if (chosen)
+        out.add(chosen);
+    const auto = keychainStore({ ...env, PROMIGENCE_CREDENTIAL_STORE: "auto" }, platform);
+    if (auto)
+        out.add(auto);
+    return [...out];
+}
+const LOCKED = /interaction is not allowed|is locked/i;
+function failureText(e) {
+    if (e.code === "ENOENT")
+        return "its command-line tool is not installed";
+    if (e.code === "ETIMEDOUT" || e.signal === "SIGTERM")
+        return "it did not answer in time";
+    const stderr = String(e.stderr ?? "");
+    if (LOCKED.test(stderr))
+        return "it is locked (an SSH session cannot unlock it)";
+    if (/default keychain could not be found|keychain could not be found|No such keychain/i.test(stderr))
+        return "there is no default keychain";
+    if (/authorization was canceled|canceled by the user/i.test(stderr))
+        return "access was not allowed";
+    if (/Cannot autolaunch D-Bus|org\.freedesktop|D-Bus|dbus/i.test(stderr))
+        return "no Secret Service is answering on the session bus";
+    return `exit ${e.status ?? "?"}`;
+}
+function maybeHex(out) {
+    if (out.length >= 2 && out.length % 2 === 0 && /^[0-9a-f]+$/i.test(out)) {
+        const text = Buffer.from(out, "hex").toString("utf8");
+        if (text.startsWith("{"))
+            return text;
+    }
+    return out;
+}
+const READ_TIMEOUT_MS = 10_000;
+const WRITE_TIMEOUT_MS = 60_000;
+function runTool(store, args, env, input, timeout) {
+    const bin = onPath(toolName(store), env);
+    if (bin === undefined)
+        throw Object.assign(new Error(`${toolName(store)} not found`), { code: "ENOENT" });
+    const h = store === "macos-keychain" && !env["HOME"] ? userHome(env) : undefined;
+    return (0, node_child_process_1.execFileSync)(bin, args, {
+        encoding: "utf8", timeout, env: h ? { ...env, HOME: h } : env,
+        ...(input === undefined ? { stdio: ["ignore", "pipe", "pipe"] } : { input, stdio: ["pipe", "pipe", "pipe"] }),
+    });
+}
+function keychainRead(store, account, env = process.env) {
+    const args = store === "macos-keychain"
+        ? ["find-generic-password", "-s", exports.KEYCHAIN_SERVICE, "-a", account, "-w"]
+        : ["lookup", "service", exports.KEYCHAIN_SERVICE, "account", account];
+    try {
+        const text = maybeHex(runTool(store, args, env, undefined, READ_TIMEOUT_MS).replace(/\r?\n$/, ""));
+        return text ? { status: "found", text } : { status: "absent" };
+    }
+    catch (e) {
+        const f = e;
+        const stderr = String(f.stderr ?? "");
+        if (store === "macos-keychain" && f.status === 44)
+            return { status: "absent" };
+        if (store === "secret-service" && f.status === 1 && !stderr.trim())
+            return { status: "absent" };
+        return { status: "unavailable", reason: failureText(f), locked: LOCKED.test(stderr) || (store === "macos-keychain" && f.status === 36) };
+    }
+}
+function quotable(account) {
+    return /^[^"\\\u0000-\u001f\u007f]+$/.test(account);
+}
+function macosDefaultKeychain(env) {
+    try {
+        const p = runTool("macos-keychain", ["default-keychain", "-d", "user"], env, undefined, READ_TIMEOUT_MS).trim().replace(/^"|"$/g, "");
+        return p.length > 0 && (0, node_fs_1.existsSync)(p);
+    }
+    catch {
+        return false;
+    }
+}
+const MAX_SECURITY_LINE = 2048;
+function keychainWrite(store, account, text, env = process.env) {
+    try {
+        if (store === "macos-keychain") {
+            if (!quotable(account))
+                return { ok: false, reason: "the credentials path holds a quote, backslash or control character" };
+            if (!macosDefaultKeychain(env))
+                return { ok: false, reason: "there is no default keychain" };
+            const hex = Buffer.from(text, "utf8").toString("hex");
+            const line = `add-generic-password -U -s "${exports.KEYCHAIN_SERVICE}" -a "${account}" -l "${KEYCHAIN_LABEL}" -X ${hex}\n`;
+            if (line.length > MAX_SECURITY_LINE)
+                return { ok: false, reason: "the sign-in is too long for the keychain tool's command reader" };
+            runTool(store, ["-i"], env, line, WRITE_TIMEOUT_MS);
+        }
+        else {
+            runTool(store, ["store", `--label=${KEYCHAIN_LABEL}`, "service", exports.KEYCHAIN_SERVICE, "account", account], env, text, WRITE_TIMEOUT_MS);
+        }
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, reason: failureText(e) };
+    }
+}
+function keychainDelete(store, account, env = process.env) {
+    const args = store === "macos-keychain"
+        ? ["delete-generic-password", "-s", exports.KEYCHAIN_SERVICE, "-a", account]
+        : ["clear", "service", exports.KEYCHAIN_SERVICE, "account", account];
+    try {
+        runTool(store, args, env, undefined, WRITE_TIMEOUT_MS);
+        return { ok: true, absent: false };
+    }
+    catch (e) {
+        const f = e;
+        if (store === "macos-keychain" && f.status === 44)
+            return { ok: true, absent: true };
+        if (f.code === "ENOENT")
+            return { ok: true, absent: true };
+        return { ok: false, reason: failureText(f), locked: LOCKED.test(String(f.stderr ?? "")) };
+    }
+}
+function encodeCredentials(body) {
+    return JSON.stringify(body).replace(/[\u007f-￿]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+const CACHE_TTL_MS = 30_000;
+const cache = new Map();
+const cacheKey = (store, account) => `${store}\u0000${account}`;
+function keychainReadCached(store, account, env = process.env) {
+    const k = cacheKey(store, account);
+    const hit = cache.get(k);
+    if (hit && Date.now() - hit.at < CACHE_TTL_MS)
+        return hit.value;
+    const value = keychainRead(store, account, env);
+    if (value.status !== "unavailable")
+        cache.set(k, { at: Date.now(), value });
+    return value;
+}
+function keychainCacheSet(store, account, text) {
+    cache.set(cacheKey(store, account), { at: Date.now(), value: text === undefined ? { status: "absent" } : { status: "found", text } });
+}
+function forgetKeychainReads() {
+    cache.clear();
+}

package/dist/cjs/dispatcher.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The dispatcher for a request that may legitimately outlast Node's `fetch`.
+ *
+ * On Node.js `globalThis.fetch` is undici, and undici's dispatcher fails any request whose
+ * response headers have not arrived 300 s after it was sent (`headersTimeout`, error code
+ * `UND_ERR_HEADERS_TIMEOUT`) and any body that stalls for 300 s (`bodyTimeout`), whatever
+ * `AbortSignal` the caller gave it. A foreground exec (`POST /sandboxes/:id/execs`) is ONE
+ * request that lasts as long as the command runs, so a six-minute build failed client-side at
+ * 300 s and was reported "unreachable" while the sandbox and the command were fine. `pause` and
+ * `snapshot` carry a ten-minute bound and were exposed the same way. The HTTP/2 transport has no
+ * socket-level timeout of its
+ * own and is bounded by the request's signal alone, so it never had this problem — but every
+ * request it hands back to `fetch` did.
+ *
+ * The rule: a request whose bound plus a minute of slack exceeds undici's default carries a
+ * `dispatcher` whose `headersTimeout` and `bodyTimeout` are at least that, so the SDK's own
+ * `AbortSignal.timeout` is always the timer that fires first and the error a customer sees names
+ * the bound they can raise. The dispatcher is the process's global one composed with a single
+ * interceptor that sets the two timeouts on each request (undici's `Dispatcher.compose`; verified
+ * on Node 22.19 / undici 6.21 and Node 26.10 / undici 8.10): the same connection pool, the same
+ * proxy or mock agent if the caller installed one, the same TLS options — only the timeouts
+ * change. One composed dispatcher per five-minute bucket of timeout, per global dispatcher,
+ * shared by every client in the process.
+ *
+ * Feature-detected, no dependency: where there is no global dispatcher (Bun, Deno, a browser),
+ * no `compose` (an older undici), or anything about it looks unfamiliar, nothing is attached and
+ * the request travels exactly as it did before. The worst case is the old behaviour, never a
+ * request that fails for a new reason.
+ */
+/** undici's default `headersTimeout` and `bodyTimeout`: what a request without a dispatcher gets. */
+export declare const FETCH_DEFAULT_TIMEOUT_MS = 300000;
+/** Margin between the SDK's bound and the socket-level timeout, so the SDK's is the one that fires. */
+export declare const LONG_REQUEST_SLACK_MS = 60000;
+/**
+ * True when someone called undici's `setGlobalDispatcher` (a proxy agent, a mock agent). `fetch`
+ * reads the dispatcher on every call, so this is checked on every request, not once. An unknown
+ * name counts as custom: the safe direction is `fetch`.
+ */
+export declare function customDispatcher(): boolean;
+interface Timeouts {
+    headersTimeout: number;
+    bodyTimeout: number;
+}
+/**
+ * The dispatcher a request bounded by `timeoutMs` should carry, or `undefined` when the default
+ * already waits long enough or nothing better can be had here. Never throws.
+ */
+export declare function longRequestDispatcher(timeoutMs: number, base?: object | undefined): object | undefined;
+/** Test and diagnostics view. Not part of the public API. */
+export declare const __dispatcherInternals: {
+    /** The timeouts a dispatcher of ours sets, or `undefined` for any other value. */
+    timeoutsOf(d: unknown): Timeouts | undefined;
+    /** The process's global dispatcher composed with exactly these timeouts (never cached). */
+    composeWith(ms: number): object | undefined;
+    /** Forget every composed dispatcher. */
+    reset(): void;
+};
+export {};

package/dist/cjs/dispatcher.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__dispatcherInternals = exports.LONG_REQUEST_SLACK_MS = exports.FETCH_DEFAULT_TIMEOUT_MS = void 0;
+exports.customDispatcher = customDispatcher;
+exports.longRequestDispatcher = longRequestDispatcher;
+exports.FETCH_DEFAULT_TIMEOUT_MS = 300_000;
+exports.LONG_REQUEST_SLACK_MS = 60_000;
+const BUCKET_MS = 5 * 60_000;
+const DEFAULT_DISPATCHERS = new Set(["Agent", "Dispatcher1Wrapper"]);
+const DISPATCHER_KEYS = [Symbol.for("undici.globalDispatcher.1"), Symbol.for("undici.globalDispatcher.2")];
+function globalDispatchers() {
+    const out = [];
+    for (let i = 0; i < DISPATCHER_KEYS.length; i++) {
+        const d = globalDispatcher(i);
+        if (d !== undefined)
+            out.push(d);
+    }
+    return out;
+}
+function globalDispatcher(i) {
+    const d = globalThis[DISPATCHER_KEYS[i]];
+    return d !== undefined && d !== null && (typeof d === "object" || typeof d === "function") ? d : undefined;
+}
+function customDispatcher() {
+    for (let i = 0; i < DISPATCHER_KEYS.length; i++) {
+        const d = globalDispatcher(i);
+        if (d === undefined)
+            continue;
+        const name = d.constructor?.name ?? "";
+        if (!DEFAULT_DISPATCHERS.has(name))
+            return true;
+    }
+    return false;
+}
+function firstGlobalDispatcher() {
+    for (let i = 0; i < DISPATCHER_KEYS.length; i++) {
+        const d = globalDispatcher(i);
+        if (d !== undefined)
+            return d;
+    }
+    return undefined;
+}
+let composed = new WeakMap();
+const timeouts = new WeakMap();
+function composeWith(base, ms) {
+    const b = base;
+    if (typeof b.compose !== "function")
+        return undefined;
+    const d = b.compose((dispatch) => (opts, handler) => dispatch({ ...opts, headersTimeout: ms, bodyTimeout: ms }, handler));
+    if (d === null || typeof d !== "object" || typeof d.dispatch !== "function")
+        return undefined;
+    timeouts.set(d, { headersTimeout: ms, bodyTimeout: ms });
+    return d;
+}
+function longRequestDispatcher(timeoutMs, base = firstGlobalDispatcher()) {
+    try {
+        const needed = timeoutMs + exports.LONG_REQUEST_SLACK_MS;
+        if (!(needed > exports.FETCH_DEFAULT_TIMEOUT_MS))
+            return undefined;
+        if (base === undefined)
+            return undefined;
+        const ms = Math.ceil(needed / BUCKET_MS) * BUCKET_MS;
+        let perBase = composed.get(base);
+        if (perBase === undefined) {
+            perBase = new Map();
+            composed.set(base, perBase);
+        }
+        const hit = perBase.get(ms);
+        if (hit !== undefined)
+            return hit;
+        const d = composeWith(base, ms);
+        if (d !== undefined)
+            perBase.set(ms, d);
+        return d;
+    }
+    catch {
+        return undefined;
+    }
+}
+exports.__dispatcherInternals = {
+    timeoutsOf(d) {
+        return d !== null && typeof d === "object" ? timeouts.get(d) : undefined;
+    },
+    composeWith(ms) {
+        const base = globalDispatchers()[0];
+        return base === undefined ? undefined : composeWith(base, ms);
+    },
+    reset() {
+        composed = new WeakMap();
+    },
+};

package/dist/cjs/github.d.ts

@@ -0,0 +1,158 @@
+/**
+ * The GitHub connection (`/v1/integrations/github/*`): the answers' types, and the `POST
+ * /snapshots` body for a connected repository (`repo: "github:owner/name"`).
+ *
+ * A customer installs the platform's GitHub App once (`promigence github connect`); after that a
+ * snapshot is built from a private repository by name, with no credential ever passing through
+ * the client. Field-for-field with `sdk-py` (`_ops.github_create_body`).
+ */
+/** `POST /integrations/github/connect`: open `install_url` in a browser. */
+export interface GithubConnect {
+    install_url: string;
+    /** RFC 3339: the link works for 15 minutes. */
+    expires_at: string;
+    app_slug: string;
+}
+/** One connected GitHub account. */
+export interface GithubConnection {
+    installation_id: number;
+    account: string;
+    /** `User` or `Organization`. */
+    account_type: string;
+    /** `all` or `selected`. */
+    repository_selection: string;
+    suspended: boolean;
+    connected_at: string;
+    /** Where the account changes what the App can read, or uninstalls it. */
+    manage_url: string;
+}
+/** An install GitHub has not confirmed yet. */
+export interface GithubPending {
+    installation_id: number;
+    account?: string;
+    claimed_at: string;
+    state: string;
+    message: string;
+}
+/** A snapshot that follows a branch: every push builds it again (each build billed per second). */
+export interface GithubTrack {
+    track_id: string;
+    repo: string;
+    branch: string;
+    alias: string;
+    head_sha?: string;
+    built_sha?: string;
+    snapshot_id?: string;
+    build_id?: string;
+    last_error?: string;
+    created_at: string;
+}
+/** `GET /integrations/github`. `configured: false` on a deployment with no GitHub App. */
+export interface GithubStatus {
+    configured: boolean;
+    app_slug?: string;
+    message?: string;
+    connections: GithubConnection[];
+    pending: GithubPending[];
+    tracks: GithubTrack[];
+}
+/** `DELETE /integrations/github/installations/:installation_id`. */
+export interface GithubDisconnected {
+    installation_id: number;
+    account: string;
+    disconnected: boolean;
+    tracks_removed: number;
+    /** The App stays installed on GitHub until it is uninstalled there. */
+    uninstall_url: string;
+    message: string;
+}
+/** One repository the organization's connections can read. */
+export interface GithubRepo {
+    /** `owner/name`: what `snapshots.create({ repo: "github:owner/name" })` takes. */
+    full_name: string;
+    private: boolean;
+    default_branch: string;
+    installation_id: number;
+    account: string;
+    archived: boolean;
+    pushed_at?: string;
+}
+/** `GET /integrations/github/repos`: one page, across every connection. */
+export interface GithubRepos {
+    repos: GithubRepo[];
+    page: number;
+    per_page: number;
+    total: number;
+    has_more: boolean;
+}
+/** `DELETE /integrations/github/tracks/:track_id`: the snapshot stays; pushes stop rebuilding it. */
+export interface GithubUntracked {
+    track_id: string;
+    repo: string;
+    branch: string;
+    alias: string;
+    untracked: boolean;
+}
+/**
+ * One request to connect a code host (`github` or `gitlab`), started by you, and how it ended.
+ * `state` is `pending` until it ends, then `connected`, `updated`, `already_connected`,
+ * `pending_provider_approval`, `declined`, `other_org`, `needs_admin`, `not_installer`,
+ * `wrong_user`, `expired` or `failed`; `message` says what happened and what to do next.
+ */
+export interface ConnectRequest {
+    request_id: string;
+    provider: string;
+    state: string;
+    account?: string;
+    message: string;
+    created_at: string;
+    finished_at?: string;
+}
+/**
+ * `POST /integrations/{github,gitlab}/requests`: a connection started for you in the console. Open
+ * `connect_url` in a browser signed in to the console as you; `request_id` says how it ends.
+ */
+export interface ConnectTicket {
+    /** Used once, by you only, within 5 minutes. */
+    ticket_id: string;
+    request_id: string;
+    /** The console page that starts it: it carries the ticket and nothing else. */
+    connect_url: string;
+    expires_at: string;
+}
+/** The prefix that names a connected repository in `repo`. */
+export declare const GITHUB_REPO_PREFIX = "github:";
+/**
+ * `owner/name` or `github:owner/name` as `{ owner, name }`; `undefined` for anything else — a
+ * URL, the scp form, a path. What decides that `snapshot create --repo` means a connected
+ * repository rather than a git URL.
+ */
+export declare function parseGithubRepo(repo: string | undefined): {
+    owner: string;
+    name: string;
+} | undefined;
+/** A git ref the API takes: a branch, a tag, `heads/<branch>`, `tags/<tag>` or a commit sha. */
+export declare function validGitRef(ref: string): boolean;
+/** The options of `snapshots.create` the connected-repository form reads. */
+export interface GithubCreateInput {
+    repo: string;
+    commit?: string | undefined;
+    ref?: string | undefined;
+    from?: string | undefined;
+    track?: boolean | undefined;
+    setup?: string[] | undefined;
+    verify?: {
+        cmd: string;
+        allow_fast: boolean;
+    } | undefined;
+    tier?: string | undefined;
+    alias?: string | undefined;
+    /** Inputs of the other forms: each one present is refused, by name. */
+    others: Array<[string, boolean]>;
+}
+/**
+ * The `POST /snapshots` body for a connected repository: `repo: "github:owner/name"` or
+ * `"gitlab:group/project"`. Refuses, before anything is sent, what the API refuses: another form's
+ * inputs, `ref` with `commit`, `track` without an `alias` or with a `commit`.
+ */
+export declare function githubCreateBody(o: GithubCreateInput): Record<string, unknown>;

package/dist/cjs/github.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GITHUB_REPO_PREFIX = void 0;
+exports.parseGithubRepo = parseGithubRepo;
+exports.validGitRef = validGitRef;
+exports.githubCreateBody = githubCreateBody;
+const core_js_1 = require("./core.js");
+const gitlab_js_1 = require("./gitlab.js");
+exports.GITHUB_REPO_PREFIX = "github:";
+const OWNER_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
+const NAME_RE = /^[A-Za-z0-9._-]{1,100}$/;
+function parseGithubRepo(repo) {
+    if (typeof repo !== "string")
+        return undefined;
+    let r = repo.trim();
+    if (r.startsWith(exports.GITHUB_REPO_PREFIX))
+        r = r.slice(exports.GITHUB_REPO_PREFIX.length);
+    if (r.endsWith(".git"))
+        r = r.slice(0, -4);
+    const parts = r.split("/");
+    if (parts.length !== 2)
+        return undefined;
+    const [owner, name] = parts;
+    if (!OWNER_RE.test(owner) || !NAME_RE.test(name) || name === "." || name === "..")
+        return undefined;
+    return { owner, name };
+}
+function validGitRef(ref) {
+    return ref.length >= 1 && ref.length <= 255
+        && !ref.startsWith("-") && !ref.startsWith("/") && !ref.endsWith("/") && !ref.endsWith(".lock")
+        && !ref.includes("..") && !ref.includes("//") && !ref.includes("@{")
+        && /^[A-Za-z0-9._/+@=,-]+$/.test(ref);
+}
+function githubCreateBody(o) {
+    const gitlab = o.repo.trim().startsWith(gitlab_js_1.GITLAB_REPO_PREFIX);
+    const glPath = gitlab ? (0, gitlab_js_1.parseGitlabRepo)(o.repo) : undefined;
+    const parsed = gitlab ? undefined : parseGithubRepo(o.repo);
+    if (gitlab && !glPath) {
+        throw new core_js_1.InvalidArgumentError(`snapshots.create repo must be gitlab:group/project for a connected GitLab project, got ${JSON.stringify(o.repo)}`, "Pass { repo: 'gitlab:your-group/app', ref: 'main' }; `promigence repos --provider gitlab` lists what your connection can read.");
+    }
+    if (!gitlab && !parsed) {
+        throw new core_js_1.InvalidArgumentError(`snapshots.create repo must be github:owner/name for a connected repository, got ${JSON.stringify(o.repo)}`, "Pass { repo: 'github:your-org/app', ref: 'main' }; `promigence repos` lists what your connection can read.");
+    }
+    for (const [field, present] of o.others) {
+        if (present) {
+            throw new core_js_1.InvalidArgumentError(`snapshots.create ${field} is not taken with a ${gitlab ? "gitlab:" : "github:"} repository`, field === "sources"
+                ? "Clone further repositories in a setup step."
+                : "A connected repository builds in a sandbox of `from` (default promigence/base): pass the image as a snapshot with `from`, or drop the field.");
+        }
+    }
+    if (o.commit !== undefined && !/^[0-9a-f]{40}$/i.test(o.commit)) {
+        throw new core_js_1.InvalidArgumentError(`snapshots.create commit must be a full 40-character sha, got ${JSON.stringify(o.commit)}`, "Pass the full sha, or a branch or tag as `ref`.");
+    }
+    if (o.ref !== undefined && !validGitRef(o.ref.trim())) {
+        throw new core_js_1.InvalidArgumentError(`snapshots.create ref must be a branch, a tag or a commit sha, got ${JSON.stringify(o.ref)}`, "Pass { ref: 'main' }, { ref: 'v1.2.0' } or a commit sha.");
+    }
+    if (o.ref !== undefined && o.commit !== undefined) {
+        throw new core_js_1.InvalidArgumentError("snapshots.create takes ref or commit, not both", "Pass one: a branch or tag as `ref`, or a sha as `commit`.");
+    }
+    if (o.track && !o.alias) {
+        throw new core_js_1.InvalidArgumentError("snapshots.create track needs an alias", "Every push builds the snapshot again and moves the alias to it: pass { alias: 'app-main', track: true }.");
+    }
+    if (o.track && o.commit !== undefined) {
+        throw new core_js_1.InvalidArgumentError("snapshots.create track follows a branch, not a commit", "Pass { ref: 'main', track: true } (no ref: the default branch).");
+    }
+    const body = {
+        repo: gitlab ? `${gitlab_js_1.GITLAB_REPO_PREFIX}${glPath}` : `${exports.GITHUB_REPO_PREFIX}${parsed.owner}/${parsed.name}`,
+    };
+    if (o.ref !== undefined)
+        body["ref"] = o.ref.trim();
+    if (o.commit !== undefined)
+        body["commit"] = o.commit.toLowerCase();
+    if (o.from)
+        body["from"] = o.from;
+    if (o.setup?.length)
+        body["setup"] = [...o.setup];
+    if (o.verify)
+        body["verify"] = o.verify;
+    if (o.tier !== undefined)
+        body["tier"] = o.tier;
+    if (o.track)
+        body["track"] = true;
+    return body;
+}