@simplysf/simply-gitlab-core 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# @simplysf/simply-gitlab-core
+
+Configuration, authentication, the HTTP client, and the shared logic that
+[`@simplysf/simply-gitlab`](../simply-gitlab) (the CLI) and
+[`@simplysf/simply-gitlab-mcp`](../simply-gitlab-mcp) (the MCP server) are both built on.
+
+Everything a command does between parsing its input and rendering its result lives here, so the CLI
+and the MCP server cannot disagree about what a rule means. Nothing in this package 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.
+
+You want this package directly if you are building something else against GitLab in TypeScript. If
+you want a CLI or an MCP server, install one of those instead.
+
+```sh
+npm install @simplysf/simply-gitlab-core
+```
+
+## Usage
+
+```ts
+import { GitLabClient, resolveGitLabConfig } from '@simplysf/simply-gitlab-core';
+
+// Reads GITLAB_URL (default https://gitlab.com) and GITLAB_TOKEN, and throws a ConfigError
+// naming what is missing.
+const client = new GitLabClient(resolveGitLabConfig());
+
+// A project is named by numeric id or by full path; the path is encoded for you.
+const project = await client.getProject('group/subgroup/project');
+
+// Lists follow pages up to your limit and tell you whether they got everything.
+const { items, total, complete } = await client.listMergeRequests('group/project', { state: 'opened' }, 50);
+if (!complete) console.warn(`showing ${items.length} of ${total ?? 'many'}`);
+```
+
+## What is in here
+
+**Configuration and auth** — `resolveGitLabConfig`, `buildAuthHeaders`, `loadEnvFile`.
+
+**Transport** — `HttpTransport`, with retries on 429 and 5xx, a capped `Retry-After`, a 30s deadline
+covering the response body, GitLab's bracketed array query parameters, a non-JSON mode for job
+traces, and its offset-pagination headers.
+
+**The client** — `GitLabClient`, which owns project-path encoding and page walking, and returns
+`{ items, total?, pages, complete }` from every list.
+
+**Errors** — `ConfigError` (exit 2), `AuthError` (3), `NetworkError` (1), `HttpError` (1), all
+extending `CliError`.
+
+**Safety** — `assertWritesAllowed`/`isReadOnly` for `GITLAB_READ_ONLY`; `redactSecrets` and
+`sanitiseDeep` to keep a token out of any message or response body; `stripControl` and
+`stripControlOneLine` for text the instance chose.
+
+**Operations** — `assertIid`, `buildMergeRequestCreateBody`, `buildMergeRequestUpdateBody`,
+`buildCommitBody`, `parseCommitActions`, `buildFileWrite`, `decodeFileContent`, `maskVariables`,
+`tailLog`, `searchColumns`.
+
+**Rendering** — `formatTable`, `formatKeyValue`, and the column sets each list command uses.
+
+**Testing** — `@simplysf/simply-gitlab-core/testing` exports `startTestServer` and `respondJson`, a
+tiny local HTTP server that records every request. Both other packages test against it.
+
+## Stability
+
+Every export from `src/index.ts` is semver-covered: adding one is a minor or patch change, removing
+or renaming one is breaking. `test/index.test.ts` pins the list, so a removal fails a test rather
+than shipping quietly in a patch.
+
+## Documentation
+
+- [GitLab client core design](../../docs/design/0001-gitlab-client-core.md)
+- [Contributing](./CONTRIBUTING.md)
+
+## License
+
+Apache-2.0.

package/lib/auth.d.ts

@@ -0,0 +1,9 @@
+import type { GitLabConfig } from './config.js';
+/**
+ * GitLab accepts the same token as `PRIVATE-TOKEN` or as an OAuth bearer, and the two are not
+ * interchangeable: a personal, project, or group access token authenticates only through
+ * `PRIVATE-TOKEN`, while `Authorization: Bearer` is reserved for OAuth 2 tokens. This CLI issues
+ * neither OAuth flow, so it sends the header that works for every token a user can create by
+ * hand. Returns just the header so callers can merge it into a request.
+ */
+export declare function buildAuthHeaders(config: GitLabConfig): Record<string, string>;

package/lib/auth.js

@@ -0,0 +1,26 @@
+/*
+ * 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.
+ */
+/**
+ * GitLab accepts the same token as `PRIVATE-TOKEN` or as an OAuth bearer, and the two are not
+ * interchangeable: a personal, project, or group access token authenticates only through
+ * `PRIVATE-TOKEN`, while `Authorization: Bearer` is reserved for OAuth 2 tokens. This CLI issues
+ * neither OAuth flow, so it sends the header that works for every token a user can create by
+ * hand. Returns just the header so callers can merge it into a request.
+ */
+export function buildAuthHeaders(config) {
+    return { 'PRIVATE-TOKEN': config.token };
+}
+//# sourceMappingURL=auth.js.map

package/lib/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAoB;IACnD,OAAO,EAAE,eAAe,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;AAC3C,CAAC"}

package/lib/cicd.d.ts

@@ -0,0 +1,29 @@
+/** What a hidden CI variable's value is replaced with, in both the table and the JSON. */
+export declare const HIDDEN = "<hidden>";
+/**
+ * Replaces the value of every CI/CD variable with a placeholder.
+ *
+ * `GET /projects/:id/variables` returns every variable's value in clear text — including the ones
+ * marked "masked", because masking only applies to job logs. Those values are deploy keys, signing
+ * certificates, and production credentials, and the endpoint's usual caller is a person listing
+ * variables to see *which* exist, not to read them.
+ *
+ * So the values are hidden by default and revealed only on an explicit request. This is the one
+ * place the CLI and the MCP server deliberately differ: `--reveal` exists on the command, and
+ * there is no equivalent tool input, because a value revealed to an agent is a value copied into
+ * a context window, a transcript, and whatever the agent writes next. A person who needs the
+ * value can run the command; nothing about the tool catalogue should make exfiltrating a
+ * production secret a one-call operation.
+ */
+export declare function maskVariables(items: readonly unknown[]): unknown[];
+/**
+ * Trims a job trace to its last `lines` lines.
+ *
+ * A trace is regularly tens of megabytes, and the interesting part of a failed job is at the end.
+ * Returning the whole thing by default would blow a terminal's scrollback and an agent's context
+ * for a question that is almost always "why did it fail".
+ */
+export declare function tailLog(log: string, lines: number): {
+    readonly text: string;
+    readonly truncated: boolean;
+};

package/lib/cicd.js

@@ -0,0 +1,56 @@
+/*
+ * 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.
+ */
+/** What a hidden CI variable's value is replaced with, in both the table and the JSON. */
+export const HIDDEN = '<hidden>';
+/**
+ * Replaces the value of every CI/CD variable with a placeholder.
+ *
+ * `GET /projects/:id/variables` returns every variable's value in clear text — including the ones
+ * marked "masked", because masking only applies to job logs. Those values are deploy keys, signing
+ * certificates, and production credentials, and the endpoint's usual caller is a person listing
+ * variables to see *which* exist, not to read them.
+ *
+ * So the values are hidden by default and revealed only on an explicit request. This is the one
+ * place the CLI and the MCP server deliberately differ: `--reveal` exists on the command, and
+ * there is no equivalent tool input, because a value revealed to an agent is a value copied into
+ * a context window, a transcript, and whatever the agent writes next. A person who needs the
+ * value can run the command; nothing about the tool catalogue should make exfiltrating a
+ * production secret a one-call operation.
+ */
+export function maskVariables(items) {
+    return items.map((item) => {
+        if (typeof item !== 'object' || item === null)
+            return item;
+        const variable = item;
+        return 'value' in variable ? { ...variable, value: HIDDEN } : variable;
+    });
+}
+/**
+ * Trims a job trace to its last `lines` lines.
+ *
+ * A trace is regularly tens of megabytes, and the interesting part of a failed job is at the end.
+ * Returning the whole thing by default would blow a terminal's scrollback and an agent's context
+ * for a question that is almost always "why did it fail".
+ */
+export function tailLog(log, lines) {
+    if (!Number.isInteger(lines) || lines < 1)
+        return { text: log, truncated: false };
+    const all = log.split('\n');
+    if (all.length <= lines)
+        return { text: log, truncated: false };
+    return { text: all.slice(-lines).join('\n'), truncated: true };
+}
+//# sourceMappingURL=cicd.js.map

package/lib/cicd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cicd.js","sourceRoot":"","sources":["../src/cicd.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,0FAA0F;AAC1F,MAAM,CAAC,MAAM,MAAM,GAAG,UAAU,CAAC;AAEjC;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAAC,KAAyB;IACrD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACxB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAC3D,MAAM,QAAQ,GAAG,IAA+B,CAAC;QACjD,OAAO,OAAO,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;IACzE,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,GAAW,EAAE,KAAa;IAChD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAClF,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,GAAG,CAAC,MAAM,IAAI,KAAK;QAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAChE,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AACjE,CAAC"}

package/lib/commits.d.ts

@@ -0,0 +1,34 @@
+import type { CommitAction } from './gitlab-client.js';
+/**
+ * Validates the `actions` array of a commit.
+ *
+ * GitLab answers a malformed action with a 400 whose body names neither the index nor the file,
+ * so a ten-file commit with one bad entry becomes a hunt. Every rule checked here is one GitLab
+ * itself enforces — this only moves the report to where the caller can act on it.
+ */
+export declare function parseCommitActions(value: unknown): readonly CommitAction[];
+export interface CommitInput {
+    readonly branch?: string;
+    readonly message?: string;
+    readonly actions?: unknown;
+    readonly startBranch?: string;
+    readonly startSha?: string;
+    readonly authorEmail?: string;
+    readonly authorName?: string;
+    readonly force?: boolean;
+    readonly stats?: boolean;
+    readonly body?: Record<string, unknown>;
+}
+/**
+ * Builds the body of a multi-file commit. Typed properties are merged over `body`, so a template
+ * file can supply the action list while a flag names the branch.
+ */
+export declare function buildCommitBody(input: CommitInput): Record<string, unknown>;
+/**
+ * Parses the `--actions` flag.
+ *
+ * `JSON.parse` on its own raises a SyntaxError carrying a snippet of the input, which for a flag
+ * a caller may have built from a file would echo that file's first bytes into the error. Only the
+ * position is kept, matching how `parseBodyInput` handles the same risk.
+ */
+export declare function parseActionsInput(raw: string | undefined): unknown;

package/lib/commits.js

@@ -0,0 +1,101 @@
+/*
+ * 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 { mergeBody } from './json-input.js';
+const ACTIONS = new Set(['create', 'delete', 'move', 'update', 'chmod']);
+/** What each action needs beyond `file_path`, checked before the request rather than after. */
+const REQUIRED = {
+    create: ['content'],
+    update: ['content'],
+    move: ['previous_path'],
+    delete: [],
+    chmod: ['execute_filemode'],
+};
+/**
+ * Validates the `actions` array of a commit.
+ *
+ * GitLab answers a malformed action with a 400 whose body names neither the index nor the file,
+ * so a ten-file commit with one bad entry becomes a hunt. Every rule checked here is one GitLab
+ * itself enforces — this only moves the report to where the caller can act on it.
+ */
+export function parseCommitActions(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new ConfigError('A commit needs at least one action, as a JSON array under "actions".');
+    }
+    return value.map((raw, index) => {
+        const where = `actions[${index}]`;
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+            throw new ConfigError(`${where} must be a JSON object.`);
+        }
+        const action = raw;
+        const verb = action.action;
+        if (typeof verb !== 'string' || !ACTIONS.has(verb)) {
+            throw new ConfigError(`${where}.action must be one of ${[...ACTIONS].join(', ')}.`);
+        }
+        if (typeof action.file_path !== 'string' || action.file_path === '') {
+            throw new ConfigError(`${where}.file_path is required.`);
+        }
+        for (const key of REQUIRED[verb] ?? []) {
+            if (action[key] === undefined) {
+                throw new ConfigError(`${where}.${key} is required for the "${verb}" action.`);
+            }
+        }
+        return action;
+    });
+}
+/**
+ * Builds the body of a multi-file commit. Typed properties are merged over `body`, so a template
+ * file can supply the action list while a flag names the branch.
+ */
+export function buildCommitBody(input) {
+    const merged = mergeBody(input.body, {
+        branch: input.branch,
+        commit_message: input.message,
+        actions: input.actions,
+        start_branch: input.startBranch,
+        start_sha: input.startSha,
+        author_email: input.authorEmail,
+        author_name: input.authorName,
+        force: input.force,
+        stats: input.stats,
+    });
+    if (typeof merged.branch !== 'string' || merged.branch === '') {
+        throw new ConfigError('A branch is required: pass --branch.');
+    }
+    if (typeof merged.commit_message !== 'string' || merged.commit_message === '') {
+        throw new ConfigError('A commit message is required: pass --message.');
+    }
+    return { ...merged, actions: parseCommitActions(merged.actions) };
+}
+/**
+ * Parses the `--actions` flag.
+ *
+ * `JSON.parse` on its own raises a SyntaxError carrying a snippet of the input, which for a flag
+ * a caller may have built from a file would echo that file's first bytes into the error. Only the
+ * position is kept, matching how `parseBodyInput` handles the same risk.
+ */
+export function parseActionsInput(raw) {
+    if (raw === undefined)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        const position = error instanceof Error ? /position \d+(?::? line \d+ column \d+)?/.exec(error.message)?.[0] : undefined;
+        throw new ConfigError(`--actions is not valid JSON${position === undefined ? '' : ` at ${position}`}.`);
+    }
+}
+//# sourceMappingURL=commits.js.map

package/lib/commits.js.map

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

package/lib/config.d.ts

@@ -0,0 +1,21 @@
+export interface GitLabConfig {
+    /** Instance origin, with any trailing path preserved for instances served under a subpath. */
+    readonly url: string;
+    /** Personal, project, or group access token, sent as `PRIVATE-TOKEN`. */
+    readonly token: string;
+}
+/** Per-invocation overrides, sourced from global flags. Anything set here beats the environment. */
+export interface ConfigOverrides {
+    readonly url?: string;
+    readonly token?: string;
+}
+export type EnvLike = Record<string, string | undefined>;
+export declare const URL_ENV = "GITLAB_URL";
+export declare const TOKEN_ENV = "GITLAB_TOKEN";
+/**
+ * Where an unconfigured `GITLAB_URL` points. GitLab is one product with one API, and the great
+ * majority of tokens are gitlab.com tokens, so requiring the URL would be ceremony for the common
+ * case. A self-managed instance sets the variable.
+ */
+export declare const DEFAULT_URL = "https://gitlab.com";
+export declare function resolveGitLabConfig(overrides?: ConfigOverrides, env?: EnvLike): GitLabConfig;

package/lib/config.js

@@ -0,0 +1,76 @@
+/*
+ * 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 process from 'node:process';
+import { ConfigError } from './errors.js';
+export const URL_ENV = 'GITLAB_URL';
+export const TOKEN_ENV = 'GITLAB_TOKEN';
+const SSL_VERIFY_ENV = 'GITLAB_SSL_VERIFY';
+/**
+ * Where an unconfigured `GITLAB_URL` points. GitLab is one product with one API, and the great
+ * majority of tokens are gitlab.com tokens, so requiring the URL would be ceremony for the common
+ * case. A self-managed instance sets the variable.
+ */
+export const DEFAULT_URL = 'https://gitlab.com';
+const FALSE_VALUES = new Set(['false', '0', 'no', 'off']);
+const CA_BUNDLE_HINT = 'NODE_EXTRA_CA_CERTS=/path/to/ca.pem';
+/**
+ * Parses the configured base URL. Unlike Atlassian's two deployments, every GitLab instance
+ * speaks the same `/api/v4` surface, so the only normalization needed is trimming a trailing
+ * slash — and keeping any subpath, because self-managed instances are routinely served from one
+ * (`https://example.com/gitlab`).
+ */
+function normalizeUrl(rawUrl) {
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        throw new ConfigError(`GitLab URL is not a valid URL: ${rawUrl}. Set ${URL_ENV} to something like https://gitlab.example.com.`);
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+        throw new ConfigError(`GitLab URL must use http or https, got ${parsed.protocol} (${URL_ENV}).`);
+    }
+    // A pasted project URL — https://gitlab.com/group/project — would otherwise be treated as an
+    // instance served under /group/project, and every request would 404 with nothing pointing at
+    // the cause. gitlab.com has no subpath, so the path is noise there by construction.
+    if (parsed.hostname.toLowerCase() === 'gitlab.com')
+        return parsed.origin;
+    return `${parsed.origin}${parsed.pathname.replace(/\/+$/, '')}`;
+}
+/**
+ * Certificate verification is not negotiable, so a `GITLAB_SSL_VERIFY=false` carried over from
+ * other GitLab tooling fails loudly rather than being silently ignored — the alternative is a
+ * user believing verification is off when it is on, or vice versa. The fix keeps verification
+ * intact.
+ */
+function rejectSslOptOut(env) {
+    const raw = env[SSL_VERIFY_ENV];
+    if (raw !== undefined && FALSE_VALUES.has(raw.trim().toLowerCase())) {
+        throw new ConfigError(`${SSL_VERIFY_ENV}=${raw} is not supported: this CLI always verifies TLS certificates. ` +
+            `If your GitLab instance is behind an internal or agency CA, trust that CA instead with ${CA_BUNDLE_HINT}.`);
+    }
+}
+export function resolveGitLabConfig(overrides = {}, env = process.env) {
+    rejectSslOptOut(env);
+    const rawUrl = (overrides.url ?? env[URL_ENV])?.trim();
+    const token = (overrides.token ?? env[TOKEN_ENV])?.trim();
+    if (!token) {
+        throw new ConfigError(`GitLab authentication requires a token. Set ${TOKEN_ENV} or pass --gitlab-token. ` +
+            'Create one under Preferences > Access tokens with the api scope (read_api is enough for read-only use).');
+    }
+    return { url: normalizeUrl(rawUrl === undefined || rawUrl === '' ? DEFAULT_URL : rawUrl), token };
+}
+//# sourceMappingURL=config.js.map

package/lib/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,OAAO,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAiB1C,MAAM,CAAC,MAAM,OAAO,GAAG,YAAY,CAAC;AACpC,MAAM,CAAC,MAAM,SAAS,GAAG,cAAc,CAAC;AACxC,MAAM,cAAc,GAAG,mBAAmB,CAAC;AAE3C;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,oBAAoB,CAAC;AAEhD,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;AAC1D,MAAM,cAAc,GAAG,qCAAqC,CAAC;AAE7D;;;;;GAKG;AACH,SAAS,YAAY,CAAC,MAAc;IAClC,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,WAAW,CACnB,kCAAkC,MAAM,SAAS,OAAO,gDAAgD,CACzG,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAChE,MAAM,IAAI,WAAW,CAAC,0CAA0C,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,CAAC;IACnG,CAAC;IAED,6FAA6F;IAC7F,6FAA6F;IAC7F,oFAAoF;IACpF,IAAI,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,KAAK,YAAY;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC;IAEzE,OAAO,GAAG,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC;AAClE,CAAC;AAED;;;;;GAKG;AACH,SAAS,eAAe,CAAC,GAAY;IACnC,MAAM,GAAG,GAAG,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,IAAI,GAAG,KAAK,SAAS,IAAI,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;QACpE,MAAM,IAAI,WAAW,CACnB,GAAG,cAAc,IAAI,GAAG,gEAAgE;YACtF,0FAA0F,cAAc,GAAG,CAC9G,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,YAA6B,EAAE,EAAE,MAAe,OAAO,CAAC,GAAG;IAC7F,eAAe,CAAC,GAAG,CAAC,CAAC;IAErB,MAAM,MAAM,GAAG,CAAC,SAAS,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;IACvD,MAAM,KAAK,GAAG,CAAC,SAAS,CAAC,KAAK,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;IAE1D,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,WAAW,CACnB,+CAA+C,SAAS,2BAA2B;YACjF,yGAAyG,CAC5G,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,GAAG,EAAE,YAAY,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;AACpG,CAAC"}

package/lib/env-file.d.ts

@@ -0,0 +1,11 @@
+/** Parses `.env` contents into pairs, ignoring blanks, comments, and malformed lines. */
+export declare function parseEnvFile(contents: string): Record<string, string>;
+/**
+ * Loads a `.env` file into `env`, leaving any variable that is already set untouched — the real
+ * environment and explicit flags outrank the file. A path the user named explicitly but that
+ * cannot be read is a `ConfigError`: silently continuing would leave the caller (often an agent)
+ * guessing why its credentials vanished.
+ *
+ * Only GitLab connection variables are applied; every other entry in the file is ignored.
+ */
+export declare function loadEnvFile(path: string, env?: NodeJS.ProcessEnv): void;

package/lib/env-file.js

@@ -0,0 +1,98 @@
+/*
+ * 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 process from 'node:process';
+import { ConfigError } from './errors.js';
+/**
+ * The only variables a `.env` file may set. Without this, a file the user did not write — one
+ * from a repo, a shared drive, or generated by an agent — could set `NODE_TLS_REJECT_UNAUTHORIZED`
+ * and turn off the certificate verification this CLI otherwise guarantees, handing the token to
+ * whoever answers. `GITLAB_SSL_VERIFY` is deliberately included so that setting it still produces the
+ * explanatory ConfigError rather than silence.
+ */
+const APPLICABLE_KEYS = new Set([
+    // Safe to allow: the real environment still wins, so a file can turn the guard on but never
+    // off. A read-only credential file carrying this is the intended arrangement.
+    'GITLAB_READ_ONLY',
+    'GITLAB_URL',
+    'GITLAB_TOKEN',
+    'GITLAB_SSL_VERIFY',
+]);
+/** Matches `KEY=value`, tolerating a leading `export` and surrounding whitespace. */
+const ASSIGNMENT = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/;
+/**
+ * Strips one layer of matching quotes. Only double quotes get escape processing, matching how
+ * shells treat them — `\n` in a single-quoted value is two literal characters.
+ */
+function unquote(raw) {
+    const value = raw.trim();
+    const quote = value.startsWith('"') ? '"' : value.startsWith("'") ? "'" : undefined;
+    if (quote !== undefined) {
+        // Anything after the closing quote is a comment, so a quoted value keeps its content even
+        // when the line ends in `# note` — otherwise the quotes end up inside the credential.
+        const closingAt = value.indexOf(quote, 1);
+        if (closingAt !== -1) {
+            const inner = value.slice(1, closingAt);
+            // Only double quotes carry escapes, matching how a shell treats them.
+            return quote === '"' ? inner.replaceAll('\\n', '\n').replaceAll('\\"', '"') : inner;
+        }
+        // Unterminated quote: fall through and treat the rest as a plain value.
+    }
+    // Unquoted values stop at an inline comment: `TOKEN=abc # note` is the token `abc`.
+    const commentAt = value.search(/\s#/);
+    return (commentAt === -1 ? value : value.slice(0, commentAt)).trim();
+}
+/** Parses `.env` contents into pairs, ignoring blanks, comments, and malformed lines. */
+export function parseEnvFile(contents) {
+    const parsed = {};
+    // An editor-written .env can start with a BOM, which would otherwise become part of the key.
+    for (const line of contents.replace(/^\uFEFF/, '').split(/\r?\n/)) {
+        if (line.trim() === '' || line.trimStart().startsWith('#'))
+            continue;
+        const match = ASSIGNMENT.exec(line);
+        if (match?.[1] !== undefined)
+            parsed[match[1]] = unquote(match[2] ?? '');
+    }
+    return parsed;
+}
+/**
+ * Loads a `.env` file into `env`, leaving any variable that is already set untouched — the real
+ * environment and explicit flags outrank the file. A path the user named explicitly but that
+ * cannot be read is a `ConfigError`: silently continuing would leave the caller (often an agent)
+ * guessing why its credentials vanished.
+ *
+ * Only GitLab connection variables are applied; every other entry in the file is ignored.
+ */
+export function loadEnvFile(path, env = process.env) {
+    let contents;
+    try {
+        contents = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        const reason = error.code === 'ENOENT' ? 'not found' : 'could not be read';
+        throw new ConfigError(`Env file ${path} ${reason}.`);
+    }
+    for (const [key, value] of Object.entries(parseEnvFile(contents))) {
+        if (!APPLICABLE_KEYS.has(key))
+            continue;
+        // A variable exported as the empty string carries no value, so it must not outrank the
+        // file the user explicitly named — otherwise `export GITLAB_TOKEN=` in a wrapper script
+        // silently discards the real token and the run fails as if nothing were configured.
+        if (env[key] === undefined || env[key] === '')
+            env[key] = value;
+    }
+}
+//# sourceMappingURL=env-file.js.map

package/lib/env-file.js.map

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

package/lib/errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Base class for every error this CLI raises deliberately. Commands surface these through
+ * oclif's `this.error(message, { exit })` so users get formatted output rather than a stack
+ * trace for expected failure modes.
+ */
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+/** Missing, malformed, or self-contradictory configuration. */
+export declare class ConfigError extends CliError {
+    constructor(message: string);
+}
+/**
+ * The instance rejected our credentials. Carries the status because 401 and 403 call for
+ * different responses: bad credentials versus a valid account without the needed permission.
+ */
+export declare class AuthError extends CliError {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/** The instance never answered: timeout, DNS miss, refused connection, or an untrusted certificate. */
+export declare class NetworkError extends CliError {
+    constructor(message: string);
+}
+/** Any other non-2xx response, carrying the status and whatever body came back. */
+export declare class HttpError extends CliError {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body?: unknown);
+}