@simplysf/simply-gitlab-core 0.1.0

package/lib/http.js

@@ -0,0 +1,285 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { AuthError, CliError, HttpError, NetworkError } from './errors.js';
+import { stripControlOneLine } from './text.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_ATTEMPTS = 3;
+const BACKOFF_BASE_MS = 500;
+const RETRY_AFTER_CAP_MS = 60_000;
+/** Certificate problems: the trust store is wrong, so retrying changes nothing. */
+const CERT_CODES = new Set([
+    'CERT_HAS_EXPIRED',
+    'DEPTH_ZERO_SELF_SIGNED_CERT',
+    'SELF_SIGNED_CERT_IN_CHAIN',
+    'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+    'ERR_TLS_CERT_ALTNAME_INVALID',
+]);
+/** Transport failures another attempt cannot fix: the host or the trust decision is wrong. */
+const PERMANENT_TRANSPORT_CODES = new Set(['ENOTFOUND', 'EAI_AGAIN', ...CERT_CODES]);
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/** Digs the syscall-level error code out of however deeply the runtime wrapped it. */
+function transportCode(error) {
+    for (let cursor = error; cursor instanceof Error; cursor = cursor.cause) {
+        const code = cursor.code;
+        if (typeof code === 'string')
+            return code;
+    }
+    return undefined;
+}
+function isAbort(error) {
+    // Deliberately not `instanceof Error`: fetch aborts reject with a DOMException, which isn't one.
+    return typeof error === 'object' && error !== null && error.name === 'AbortError';
+}
+/** Reads one `X-…` pagination header as a positive integer, or nothing if it is absent or junk. */
+function headerNumber(headers, name) {
+    const raw = headers.get(name);
+    if (raw === null || raw.trim() === '')
+        return undefined;
+    const value = Number(raw);
+    return Number.isInteger(value) && value >= 0 ? value : undefined;
+}
+function readPagination(headers) {
+    return {
+        nextPage: headerNumber(headers, 'x-next-page'),
+        total: headerNumber(headers, 'x-total'),
+        totalPages: headerNumber(headers, 'x-total-pages'),
+        perPage: headerNumber(headers, 'x-per-page'),
+    };
+}
+/**
+ * JSON-over-HTTPS transport bound to one GitLab instance. Each client owns one; everything that
+ * would otherwise be an argument (base URL, auth headers, timing) is fixed at construction so
+ * call sites stay small.
+ *
+ * Certificate verification is always on. An instance behind an internal or agency CA is
+ * supported by pointing Node at that CA — `NODE_EXTRA_CA_CERTS=/path/to/ca.pem` — which keeps
+ * verification intact rather than turning it off.
+ */
+export class HttpTransport {
+    target;
+    timeoutMs;
+    maxAttempts;
+    constructor(target) {
+        this.target = target;
+        this.timeoutMs = target.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxAttempts = target.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    }
+    /**
+     * Executes a call and parses the JSON response. 401/403 become `AuthError` immediately;
+     * 429/5xx retry with exponential backoff, deferring to a (capped) `Retry-After` when one is
+     * sent; other non-2xx become `HttpError`. Timeouts, DNS misses, and certificate failures
+     * become `NetworkError` without pointless retries; transient socket failures retry. The
+     * timeout covers the whole exchange, response body included.
+     */
+    async json(call) {
+        return (await this.send(call, 'json')).data;
+    }
+    /**
+     * The same call as {@link json}, keeping the pagination headers GitLab answered with. Separate
+     * from `json` because pagination is only meaningful for list endpoints, and a caller that
+     * ignored the headers on one would silently return a first page as if it were everything.
+     */
+    jsonPaged(call) {
+        return this.send(call, 'json');
+    }
+    /**
+     * Executes a call whose response is not JSON and returns it verbatim.
+     *
+     * Job traces are plain text and repository file contents can be raw bytes; parsing either as
+     * JSON would fail on the successful case. Errors on these endpoints still come back as JSON,
+     * and are still raised as `HttpError`, because the failure path is shared.
+     */
+    async text(call) {
+        return (await this.send(call, 'text')).data;
+    }
+    async send(call, mode) {
+        const url = this.resolve(call);
+        /* Each attempt must observe the previous one's outcome before starting — sequential awaiting
+           is the mechanism, not an accident. */
+        /* eslint-disable no-await-in-loop */
+        for (let attempt = 1;; attempt += 1) {
+            let outcome;
+            try {
+                outcome = await this.attempt(url, call, mode);
+            }
+            catch (error) {
+                const verdict = this.triage(error, call, url, attempt);
+                if (verdict !== TRANSIENT)
+                    throw verdict;
+                await delay(BACKOFF_BASE_MS * 2 ** (attempt - 1));
+                continue;
+            }
+            if (outcome.done)
+                return outcome.value;
+            if (attempt >= this.maxAttempts)
+                throw outcome.exhausted();
+            await delay(outcome.delayMs ?? BACKOFF_BASE_MS * 2 ** (attempt - 1));
+        }
+        /* eslint-enable no-await-in-loop */
+    }
+    /** Runs one attempt under a deadline that spans connection, headers, AND body. */
+    async attempt(url, call, mode) {
+        const controller = new AbortController();
+        const deadline = setTimeout(() => {
+            controller.abort();
+        }, this.timeoutMs);
+        try {
+            const headers = {
+                Accept: mode === 'json' ? 'application/json' : '*/*',
+                ...this.target.headers,
+            };
+            if (call.body !== undefined)
+                headers['Content-Type'] = 'application/json';
+            const response = await fetch(url, {
+                method: call.method,
+                headers,
+                body: call.body === undefined ? undefined : JSON.stringify(call.body),
+                signal: controller.signal,
+            });
+            if (response.status === 401 || response.status === 403) {
+                const detail = await describeBody(response);
+                // A 403 on a call that really does change data is often a credential that can read but
+                // not write, so naming that possibility saves a confusing hunt. It is phrased as an
+                // observation rather than an instruction, and gated on the caller's declared intent:
+                // an agent reading "use a credential with write scope" after an ordinary search
+                // failure would escalate its own privileges, defeating the one boundary that binds.
+                const hint = response.status === 403 && call.mutating === true
+                    ? ' This token may be read_api-scoped, or your role on the project may not permit this.'
+                    : '';
+                throw new AuthError(`Authentication failed: ${call.method} ${call.path} returned ${response.status}.${detail}${hint}`, response.status);
+            }
+            if (response.ok) {
+                const text = await response.text();
+                const pagination = readPagination(response.headers);
+                if (mode === 'text')
+                    return { done: true, value: { data: text, pagination } };
+                if (text.trim() === '')
+                    return { done: true, value: { data: {}, pagination } };
+                try {
+                    return { done: true, value: { data: JSON.parse(text), pagination } };
+                }
+                catch {
+                    throw new HttpError(`${call.method} ${call.path} returned malformed JSON.`, response.status, text);
+                }
+            }
+            if (response.status === 429 || response.status >= 500) {
+                const retryAfter = readRetryAfter(response.headers.get('retry-after'));
+                const status = response.status;
+                const detail = await describeBody(response);
+                return {
+                    done: false,
+                    delayMs: retryAfter,
+                    exhausted: () => new HttpError(`${call.method} ${call.path} failed (${status}).${detail}`, status),
+                };
+            }
+            const body = await bodyAsJsonOrText(response);
+            throw new HttpError(`${call.method} ${call.path} failed (${response.status}).${formatSnippet(body)}`, response.status, body);
+        }
+        finally {
+            clearTimeout(deadline);
+        }
+    }
+    /** Wraps raw transport failures in typed, user-explainable errors; rethrows deliberate ones. */
+    triage(error, call, url, attempt) {
+        if (error instanceof CliError)
+            return error;
+        if (isAbort(error)) {
+            return new NetworkError(`${call.method} ${call.path} did not complete within ${this.timeoutMs} ms (${url.host}).`);
+        }
+        const code = transportCode(error);
+        if (code !== undefined && PERMANENT_TRANSPORT_CODES.has(code)) {
+            const hint = CERT_CODES.has(code)
+                ? ` The certificate could not be verified. If ${url.host} is behind an internal or agency CA, point Node at that CA bundle with NODE_EXTRA_CA_CERTS=/path/to/ca.pem.`
+                : '';
+            return new NetworkError(`Cannot reach ${url.host}: ${code}.${hint}`);
+        }
+        if (attempt < this.maxAttempts) {
+            // Transient transport failure (connection reset, refused, mid-flight drop): try again.
+            return TRANSIENT;
+        }
+        const description = code ?? (error instanceof Error ? error.message : String(error));
+        return new NetworkError(`${call.method} ${call.path} failed after ${attempt} attempts: ${description}.`);
+    }
+    resolve(call) {
+        const url = new URL(this.target.baseUrl);
+        const root = url.pathname.replace(/\/+$/, '');
+        url.pathname = call.path.startsWith('/') ? `${root}${call.path}` : `${root}/${call.path}`;
+        for (const [name, value] of Object.entries(call.query ?? {})) {
+            if (value === undefined)
+                continue;
+            // GitLab reads a repeated parameter only in its bracketed form, so an array is appended as
+            // `scope[]=` per element rather than joined — a comma-joined value is taken as one literal
+            // scope and silently matches nothing.
+            if (Array.isArray(value)) {
+                for (const item of value)
+                    url.searchParams.append(`${name}[]`, String(item));
+            }
+            else {
+                url.searchParams.set(name, String(value));
+            }
+        }
+        return url;
+    }
+}
+/** Sentinel: the triage step decided this attempt's failure is worth another try. */
+const TRANSIENT = Symbol('transient-transport-failure');
+/** `Retry-After` arrives as delay-seconds or an HTTP date; both are capped so a hostile value can't park the CLI. */
+function readRetryAfter(header) {
+    if (header === null)
+        return undefined;
+    const value = header.trim();
+    if (/^\d+$/.test(value))
+        return Math.min(Number(value) * 1000, RETRY_AFTER_CAP_MS);
+    const at = Date.parse(value);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.min(Math.max(at - Date.now(), 0), RETRY_AFTER_CAP_MS);
+}
+/** Drains an error response and renders a short human-readable suffix, never throwing. */
+async function describeBody(response) {
+    return formatSnippet(await bodyAsJsonOrText(response));
+}
+async function bodyAsJsonOrText(response) {
+    const text = await response.text().catch(() => '');
+    if (text === '')
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/**
+ * Renders a response body into an error message, on one line.
+ *
+ * This is the only point where wholly server-controlled text joins an error message, so it is
+ * where the newline has to go — not at the assembled message, which also carries this CLI's own
+ * deliberate line structure. A multi-line body would otherwise forge extra stderr lines,
+ * including one shaped like this CLI's JSON error object, which a caller parsing stderr
+ * line-by-line could not tell from the real thing.
+ */
+function formatSnippet(body) {
+    if (body === undefined)
+        return '';
+    const rendered = stripControlOneLine(typeof body === 'string' ? body : JSON.stringify(body));
+    return rendered === '' ? '' : ` ${rendered}`;
+}
+//# sourceMappingURL=http.js.map

package/lib/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -0,0 +1,17 @@
+export { buildAuthHeaders } from './auth.js';
+export { DEFAULT_URL, resolveGitLabConfig, TOKEN_ENV, URL_ENV, type ConfigOverrides, type EnvLike, type GitLabConfig, } from './config.js';
+export { loadEnvFile, parseEnvFile } from './env-file.js';
+export { AuthError, CliError, ConfigError, HttpError, NetworkError } from './errors.js';
+export { HttpTransport, type JsonCall, type Paged, type Pagination, type QueryValue, type TransportTarget, } from './http.js';
+export { GitLabClient, type CommitAction, type FileOptions, type JobScope, type ListBranchesOptions, type ListCommitsOptions, type ListEnvironmentsOptions, type ListJobsOptions, type ListMergeRequestsOptions, type ListProjectsOptions, type ListResult, type ListTagsOptions, type MergeRequestState, type ProjectRef, type SearchOptions, type SearchScope, type WriteFileInput, } from './gitlab-client.js';
+export { stripControl, stripControlOneLine } from './text.js';
+export { assertWritesAllowed, isReadOnly, READ_ONLY_ENV } from './write-safety.js';
+export { collectSecrets, redactSecrets, sanitiseDeep, SECRET_ENV, secretValues } from './redaction.js';
+export { assertNotEmpty, mergeBody, parseBodyInput, readTextFile } from './json-input.js';
+export { formatKeyValue, formatTable, type Column, type Pair } from './output.js';
+export { branchColumns, commitColumns, environmentColumns, jobColumns, mergeRequestColumns, projectColumns, releaseColumns, tagColumns, variableColumns, type Row, } from './tables.js';
+export { HIDDEN, maskVariables, tailLog } from './cicd.js';
+export { buildCommitBody, parseActionsInput, parseCommitActions, type CommitInput } from './commits.js';
+export { assertIid, buildMergeRequestCreateBody, buildMergeRequestUpdateBody, mergeRequestUrl, type MergeRequestCreateInput, type MergeRequestUpdateInput, } from './merge-requests.js';
+export { buildFileWrite, decodeFileContent, type DecodedFile, type FilePayload, type FileWriteInput, } from './repository-files.js';
+export { ADVANCED_SCOPES, BASIC_SCOPES, needsAdvancedSearch, searchColumns } from './search.js';

package/lib/index.js

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+// Everything exported from this file is this package's public API and is semver-covered: adding
+// an export is a minor/patch change, but removing or renaming one is breaking.
+// `test/index.test.ts` pins the exported-key list so an accidental removal fails a test instead
+// of silently shipping in a patch release. See docs/design/0001-gitlab-client-core.md for why
+// this package is split out from `@simplysf/simply-gitlab` (the CLI).
+//
+// Nothing here touches a terminal or a process: no oclif, no child processes, no `process.argv`,
+// nothing written to stdout or stderr. `process.env` is read only through an injectable `env`
+// parameter that defaults to it. The repo's lint config enforces the import side of that rule.
+// --- Configuration, transport, client, errors ---
+export { buildAuthHeaders } from './auth.js';
+export { DEFAULT_URL, resolveGitLabConfig, TOKEN_ENV, URL_ENV, } from './config.js';
+export { loadEnvFile, parseEnvFile } from './env-file.js';
+export { AuthError, CliError, ConfigError, HttpError, NetworkError } from './errors.js';
+export { HttpTransport, } from './http.js';
+export { GitLabClient, } from './gitlab-client.js';
+export { stripControl, stripControlOneLine } from './text.js';
+// --- Safety: the read-only guard and credential redaction, shared by every consumer ---
+export { assertWritesAllowed, isReadOnly, READ_ONLY_ENV } from './write-safety.js';
+export { collectSecrets, redactSecrets, sanitiseDeep, SECRET_ENV, secretValues } from './redaction.js';
+// --- Shared input handling and rendering ---
+export { assertNotEmpty, mergeBody, parseBodyInput, readTextFile } from './json-input.js';
+export { formatKeyValue, formatTable } from './output.js';
+export { branchColumns, commitColumns, environmentColumns, jobColumns, mergeRequestColumns, projectColumns, releaseColumns, tagColumns, variableColumns, } from './tables.js';
+// --- Operations: what each command does between parsing its input and rendering its result ---
+export { HIDDEN, maskVariables, tailLog } from './cicd.js';
+export { buildCommitBody, parseActionsInput, parseCommitActions } from './commits.js';
+export { assertIid, buildMergeRequestCreateBody, buildMergeRequestUpdateBody, mergeRequestUrl, } from './merge-requests.js';
+export { buildFileWrite, decodeFileContent, } from './repository-files.js';
+export { ADVANCED_SCOPES, BASIC_SCOPES, needsAdvancedSearch, searchColumns } from './search.js';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,gGAAgG;AAChG,+EAA+E;AAC/E,gGAAgG;AAChG,8FAA8F;AAC9F,sEAAsE;AACtE,EAAE;AACF,iGAAiG;AACjG,8FAA8F;AAC9F,+FAA+F;AAE/F,mDAAmD;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,SAAS,EACT,OAAO,GAIR,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EACL,aAAa,GAMd,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,YAAY,GAiBb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAE9D,yFAAyF;AACzF,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACnF,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEvG,8CAA8C;AAC9C,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC1F,OAAO,EAAE,cAAc,EAAE,WAAW,EAA0B,MAAM,aAAa,CAAC;AAClF,OAAO,EACL,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,UAAU,EACV,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,UAAU,EACV,eAAe,GAEhB,MAAM,aAAa,CAAC;AAErB,gGAAgG;AAChG,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,kBAAkB,EAAoB,MAAM,cAAc,CAAC;AACxG,OAAO,EACL,SAAS,EACT,2BAA2B,EAC3B,2BAA2B,EAC3B,eAAe,GAGhB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,cAAc,EACd,iBAAiB,GAIlB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/lib/json-input.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Reads a raw JSON request body from a flag or a file. GitLab's merge-request and commit
+ * endpoints accept far more attributes than it is worth giving a flag each — squash options,
+ * approval rules, milestone ids — and the set grows without our involvement, so an escape hatch
+ * means an unusual attribute never blocks anyone, while the typed flags keep the common case
+ * simple.
+ *
+ * Exactly one source is allowed. Accepting both and picking a winner would make a caller's
+ * mistake look like a preference.
+ */
+export declare function parseBodyInput(body: string | undefined, bodyFile: string | undefined): Record<string, unknown> | undefined;
+/** Reads a file a caller named explicitly, reporting the path rather than a raw errno. */
+export declare function readTextFile(path: string, label: string): string;
+/**
+ * Merges typed flags over a raw body, dropping the flags the caller left unset.
+ *
+ * A template file can supply the shape while a flag overrides a single value, which is the way
+ * both are actually used together. GitLab request bodies are flat — unlike Jira's, there is no
+ * nested `fields` object — so a shallow merge is the whole rule.
+ */
+export declare function mergeBody(body: Record<string, unknown> | undefined, typed: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Requires at least one attribute to change.
+ *
+ * GitLab answers an empty `PUT` with 200 and an unchanged object, so without this a caller who
+ * misspelled a flag would be told the update succeeded and see nothing different.
+ */
+export declare function assertNotEmpty(body: Record<string, unknown>, what: string): Record<string, unknown>;

package/lib/json-input.js

@@ -0,0 +1,84 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { readFileSync } from 'node:fs';
+import { ConfigError } from './errors.js';
+/**
+ * Reads a raw JSON request body from a flag or a file. GitLab's merge-request and commit
+ * endpoints accept far more attributes than it is worth giving a flag each — squash options,
+ * approval rules, milestone ids — and the set grows without our involvement, so an escape hatch
+ * means an unusual attribute never blocks anyone, while the typed flags keep the common case
+ * simple.
+ *
+ * Exactly one source is allowed. Accepting both and picking a winner would make a caller's
+ * mistake look like a preference.
+ */
+export function parseBodyInput(body, bodyFile) {
+    if (body !== undefined && bodyFile !== undefined) {
+        throw new ConfigError('Pass --body or --body-file, not both.');
+    }
+    const source = body ?? (bodyFile === undefined ? undefined : readTextFile(bodyFile, 'Body file'));
+    if (source === undefined)
+        return undefined;
+    const label = bodyFile ?? '--body';
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch (error) {
+        // Only the position, never the parser's snippet of the content: a caller can name any path,
+        // and the snippet would echo the first bytes of whatever file that was.
+        const position = error instanceof Error ? /position \d+(?::? line \d+ column \d+)?/.exec(error.message)?.[0] : undefined;
+        throw new ConfigError(`${label} is not valid JSON${position === undefined ? '' : ` at ${position}`}.`);
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new ConfigError(`${label} must be a JSON object.`);
+    }
+    return parsed;
+}
+/** Reads a file a caller named explicitly, reporting the path rather than a raw errno. */
+export function readTextFile(path, label) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        const reason = error.code === 'ENOENT' ? 'not found' : 'could not be read';
+        throw new ConfigError(`${label} ${path} ${reason}.`);
+    }
+}
+/**
+ * Merges typed flags over a raw body, dropping the flags the caller left unset.
+ *
+ * A template file can supply the shape while a flag overrides a single value, which is the way
+ * both are actually used together. GitLab request bodies are flat — unlike Jira's, there is no
+ * nested `fields` object — so a shallow merge is the whole rule.
+ */
+export function mergeBody(body, typed) {
+    const provided = Object.fromEntries(Object.entries(typed).filter(([, value]) => value !== undefined));
+    return { ...(body ?? {}), ...provided };
+}
+/**
+ * Requires at least one attribute to change.
+ *
+ * GitLab answers an empty `PUT` with 200 and an unchanged object, so without this a caller who
+ * misspelled a flag would be told the update succeeded and see nothing different.
+ */
+export function assertNotEmpty(body, what) {
+    if (Object.keys(body).length === 0) {
+        throw new ConfigError(`Nothing to change: name at least one attribute to update on this ${what}.`);
+    }
+    return body;
+}
+//# sourceMappingURL=json-input.js.map

package/lib/json-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-input.js","sourceRoot":"","sources":["../src/json-input.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAwB,EACxB,QAA4B;IAE5B,IAAI,IAAI,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QACjD,MAAM,IAAI,WAAW,CAAC,uCAAuC,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC;IAClG,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAE3C,MAAM,KAAK,GAAG,QAAQ,IAAI,QAAQ,CAAC;IACnC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,4FAA4F;QAC5F,wEAAwE;QACxE,MAAM,QAAQ,GACZ,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,yCAAyC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC1G,MAAM,IAAI,WAAW,CAAC,GAAG,KAAK,qBAAqB,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,QAAQ,EAAE,GAAG,CAAC,CAAC;IACzG,CAAC;IAED,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,WAAW,CAAC,GAAG,KAAK,yBAAyB,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,MAAiC,CAAC;AAC3C,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,KAAa;IACtD,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAI,KAA+B,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,mBAAmB,CAAC;QACtG,MAAM,IAAI,WAAW,CAAC,GAAG,KAAK,IAAI,IAAI,IAAI,MAAM,GAAG,CAAC,CAAC;IACvD,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CACvB,IAAyC,EACzC,KAA8B;IAE9B,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC;IACtG,OAAO,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,GAAG,QAAQ,EAAE,CAAC;AAC1C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAA6B,EAAE,IAAY;IACxE,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,WAAW,CAAC,oEAAoE,IAAI,GAAG,CAAC,CAAC;IACrG,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/lib/merge-requests.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Merge requests are addressed by their per-project `iid`, not the instance-wide `id`, and both
+ * are bare integers that appear side by side in every payload. Passing the wrong one does not
+ * fail: it silently addresses a different merge request in a different project that happens to
+ * share the number. So the value is validated as an iid — small, positive, whole — and the error
+ * says which of the two fields to read.
+ */
+export declare function assertIid(value: unknown, what?: string): number;
+export interface MergeRequestCreateInput {
+    readonly sourceBranch?: string;
+    readonly targetBranch?: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly assigneeIds?: readonly number[];
+    readonly reviewerIds?: readonly number[];
+    readonly labels?: readonly string[];
+    readonly milestoneId?: number;
+    readonly removeSourceBranch?: boolean;
+    readonly squash?: boolean;
+    readonly draft?: boolean;
+    readonly targetProjectId?: number;
+    readonly body?: Record<string, unknown>;
+}
+export declare function buildMergeRequestCreateBody(input: MergeRequestCreateInput): Record<string, unknown>;
+export interface MergeRequestUpdateInput {
+    readonly title?: string;
+    readonly description?: string;
+    readonly targetBranch?: string;
+    readonly assigneeIds?: readonly number[];
+    readonly reviewerIds?: readonly number[];
+    readonly labels?: readonly string[];
+    readonly milestoneId?: number;
+    readonly removeSourceBranch?: boolean;
+    readonly squash?: boolean;
+    readonly stateEvent?: 'close' | 'reopen';
+    readonly body?: Record<string, unknown>;
+}
+export declare function buildMergeRequestUpdateBody(input: MergeRequestUpdateInput): Record<string, unknown>;
+/** The web URL of a created or updated merge request, when the payload carries one. */
+export declare function mergeRequestUrl(payload: unknown): string | undefined;

package/lib/merge-requests.js

@@ -0,0 +1,89 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { ConfigError } from './errors.js';
+import { assertNotEmpty, mergeBody } from './json-input.js';
+/**
+ * Merge requests are addressed by their per-project `iid`, not the instance-wide `id`, and both
+ * are bare integers that appear side by side in every payload. Passing the wrong one does not
+ * fail: it silently addresses a different merge request in a different project that happens to
+ * share the number. So the value is validated as an iid — small, positive, whole — and the error
+ * says which of the two fields to read.
+ */
+export function assertIid(value, what = 'merge request') {
+    const iid = typeof value === 'string' ? Number(value) : value;
+    if (typeof iid !== 'number' || !Number.isInteger(iid) || iid < 1) {
+        throw new ConfigError(`A ${what} is addressed by its project-scoped iid: a positive whole number, got ${JSON.stringify(value)}. ` +
+            'It is the number in the web URL and the "iid" field of the API payload, not "id".');
+    }
+    return iid;
+}
+/** GitLab marks a draft by the title prefix; there is no separate flag on the create endpoint. */
+const DRAFT_PREFIX = 'Draft: ';
+export function buildMergeRequestCreateBody(input) {
+    const title = input.title !== undefined && input.draft === true && !input.title.startsWith(DRAFT_PREFIX)
+        ? `${DRAFT_PREFIX}${input.title}`
+        : input.title;
+    const merged = mergeBody(input.body, {
+        source_branch: input.sourceBranch,
+        target_branch: input.targetBranch,
+        title,
+        description: input.description,
+        assignee_ids: input.assigneeIds,
+        reviewer_ids: input.reviewerIds,
+        labels: input.labels === undefined ? undefined : input.labels.join(','),
+        milestone_id: input.milestoneId,
+        remove_source_branch: input.removeSourceBranch,
+        squash: input.squash,
+        target_project_id: input.targetProjectId,
+    });
+    // Checked here so the refusal names the flag. GitLab's own 400 for a missing source branch is
+    // `{"message":{"source_branch":["can't be blank"]}}`, which does not say how to supply one.
+    for (const [key, flag] of [
+        ['source_branch', '--source-branch'],
+        ['target_branch', '--target-branch'],
+        ['title', '--title'],
+    ]) {
+        if (typeof merged[key] !== 'string' || merged[key] === '') {
+            throw new ConfigError(`A ${key.replace('_', ' ')} is required: pass ${flag}.`);
+        }
+    }
+    return merged;
+}
+export function buildMergeRequestUpdateBody(input) {
+    return assertNotEmpty(mergeBody(input.body, {
+        title: input.title,
+        description: input.description,
+        target_branch: input.targetBranch,
+        assignee_ids: input.assigneeIds,
+        reviewer_ids: input.reviewerIds,
+        // Deliberately `labels`, which replaces the whole set, rather than add_labels/remove_labels.
+        // One verb per flag: a flag that sometimes adds and sometimes replaces is the kind of thing
+        // a caller discovers by losing labels.
+        labels: input.labels === undefined ? undefined : input.labels.join(','),
+        milestone_id: input.milestoneId,
+        remove_source_branch: input.removeSourceBranch,
+        squash: input.squash,
+        state_event: input.stateEvent,
+    }), 'merge request');
+}
+/** The web URL of a created or updated merge request, when the payload carries one. */
+export function mergeRequestUrl(payload) {
+    if (typeof payload !== 'object' || payload === null)
+        return undefined;
+    const url = payload.web_url;
+    return typeof url === 'string' ? url : undefined;
+}
+//# sourceMappingURL=merge-requests.js.map

package/lib/merge-requests.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-requests.js","sourceRoot":"","sources":["../src/merge-requests.ts"],"names":[],"mappings":"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"}

package/lib/output.d.ts

@@ -0,0 +1,14 @@
+/** One labelled value in a detail view. `undefined` values are dropped, not printed as blanks. */
+export type Pair = readonly [label: string, value: unknown];
+export interface Column<Row> {
+    readonly header: string;
+    readonly value: (row: Row) => unknown;
+}
+export { stripControl, stripControlOneLine } from './text.js';
+/** Aligned `Label: value` lines for a single entity. */
+export declare function formatKeyValue(pairs: readonly Pair[]): string;
+/**
+ * Two-space-separated columns with a header rule. Every column is sized to its widest cell, and
+ * the last column is never padded so trailing whitespace never lands in a pipeline.
+ */
+export declare function formatTable<Row>(rows: readonly Row[], columns: ReadonlyArray<Column<Row>>): string;