@simplysf/simply-gitlab-core 0.1.0

package/lib/output.js

@@ -0,0 +1,65 @@
+/*
+ * 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.
+ */
+const EM_DASH = '—';
+import { stripControl, stripControlOneLine } from './text.js';
+export { stripControl, stripControlOneLine } from './text.js';
+/** Renders any API value as one line of terminal text; missing values read as an em dash. */
+function cell(value) {
+    if (value === null || value === undefined || value === '')
+        return EM_DASH;
+    if (typeof value === 'string')
+        return stripControlOneLine(value);
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return stripControl(JSON.stringify(value));
+}
+/** Right-pads to `width`, counting characters (adequate for the ASCII-ish fields we render). */
+function pad(text, width) {
+    return text.length >= width ? text : text + ' '.repeat(width - text.length);
+}
+/** Aligned `Label: value` lines for a single entity. */
+export function formatKeyValue(pairs) {
+    const shown = pairs.filter(([, value]) => value !== undefined);
+    if (shown.length === 0)
+        return '';
+    // Reduced for the same reason as formatTable's widths, so the dangerous pattern is not left
+    // sitting one function above the fix for it.
+    const labelWidth = shown.reduce((widest, [label]) => Math.max(widest, label.length), 0);
+    return shown.map(([label, value]) => `${pad(`${label}:`, labelWidth + 1)} ${cell(value)}`).join('\n');
+}
+/**
+ * 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 function formatTable(rows, columns) {
+    if (rows.length === 0)
+        return '';
+    const body = rows.map((row) => columns.map((column) => cell(column.value(row))));
+    // Reduced rather than spread into Math.max: `...body.map(...)` puts one argument on the stack
+    // per row, which throws RangeError somewhere past 100k rows. An instance can return that many
+    // links, and an ungraceful crash is a worse answer than a wide table.
+    const widths = columns.map((column, index) => body.reduce((widest, cells) => Math.max(widest, (cells[index] ?? '').length), column.header.length));
+    const render = (cells) => cells
+        .map((text, index) => (index === cells.length - 1 ? text : pad(text, widths[index] ?? 0)))
+        .join('  ')
+        .trimEnd();
+    return [
+        render(columns.map((column) => column.header)),
+        render(widths.map((width) => '─'.repeat(width))),
+        ...body.map(render),
+    ].join('\n');
+}
+//# sourceMappingURL=output.js.map

package/lib/output.js.map

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

package/lib/redaction.d.ts

@@ -0,0 +1,26 @@
+import type { EnvLike } from './config.js';
+/** The environment variables that carry credentials, and so must never reach any output. */
+export declare const SECRET_ENV: readonly ["GITLAB_TOKEN"];
+/**
+ * Keeps the values worth redacting out of whatever a caller collected — the environment, a
+ * command line, a config file — and drops the ones too short to be a credential.
+ */
+export declare function collectSecrets(values: Iterable<string | undefined>): Set<string>;
+/** The credential values present in an environment. */
+export declare function secretValues(env?: EnvLike): Set<string>;
+/** Blanks out any credential that could otherwise ride along in a message. */
+export declare function redactSecrets(message: string, secrets: Iterable<string>): string;
+/**
+ * Applies the same guards to a response body that an error message gets.
+ *
+ * A message that was redacted and stripped while the `body` beside it — the same bytes from the
+ * same response — went out untouched is a credential disclosure whenever the far side echoes
+ * the token back: a captive portal, a proxy, or an agency gateway does exactly that.
+ * `JSON.stringify` escapes C0 but not C1, U+2028/U+2029, or the invisible ranges, so a hostile
+ * body would also reach an agent's context with live escape sequences intact.
+ *
+ * Recursive because the body is arbitrary server JSON — GitLab nests its messages under
+ * `message` and `error` in shapes that vary by endpoint — so guarding only a top-level string
+ * would miss the common case.
+ */
+export declare function sanitiseDeep(value: unknown, secrets: Iterable<string>, depth?: number): unknown;

package/lib/redaction.js

@@ -0,0 +1,71 @@
+/*
+ * 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 { stripControl } from './text.js';
+/** The environment variables that carry credentials, and so must never reach any output. */
+export const SECRET_ENV = ['GITLAB_TOKEN'];
+/** Shorter values would mangle unrelated text; real tokens are far longer than this. */
+const MIN_SECRET_LENGTH = 8;
+/**
+ * Keeps the values worth redacting out of whatever a caller collected — the environment, a
+ * command line, a config file — and drops the ones too short to be a credential.
+ */
+export function collectSecrets(values) {
+    const secrets = new Set();
+    for (const value of values) {
+        if (value !== undefined && value.length >= MIN_SECRET_LENGTH)
+            secrets.add(value);
+    }
+    return secrets;
+}
+/** The credential values present in an environment. */
+export function secretValues(env = process.env) {
+    return collectSecrets(SECRET_ENV.map((name) => env[name]));
+}
+/** Blanks out any credential that could otherwise ride along in a message. */
+export function redactSecrets(message, secrets) {
+    let redacted = message;
+    for (const secret of secrets)
+        redacted = redacted.replaceAll(secret, '<redacted>');
+    return redacted;
+}
+/**
+ * Applies the same guards to a response body that an error message gets.
+ *
+ * A message that was redacted and stripped while the `body` beside it — the same bytes from the
+ * same response — went out untouched is a credential disclosure whenever the far side echoes
+ * the token back: a captive portal, a proxy, or an agency gateway does exactly that.
+ * `JSON.stringify` escapes C0 but not C1, U+2028/U+2029, or the invisible ranges, so a hostile
+ * body would also reach an agent's context with live escape sequences intact.
+ *
+ * Recursive because the body is arbitrary server JSON — GitLab nests its messages under
+ * `message` and `error` in shapes that vary by endpoint — so guarding only a top-level string
+ * would miss the common case.
+ */
+export function sanitiseDeep(value, secrets, depth = 0) {
+    // The body comes from the instance, so the walk is bounded rather than trusted to be shallow.
+    if (depth > 12)
+        return undefined;
+    if (typeof value === 'string')
+        return stripControl(redactSecrets(value, secrets));
+    if (Array.isArray(value))
+        return value.map((item) => sanitiseDeep(item, secrets, depth + 1));
+    if (typeof value === 'object' && value !== null) {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [stripControl(key), sanitiseDeep(item, secrets, depth + 1)]));
+    }
+    return value;
+}
+//# sourceMappingURL=redaction.js.map

package/lib/redaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.js","sourceRoot":"","sources":["../src/redaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,OAAO,MAAM,cAAc,CAAC;AAEnC,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzC,4FAA4F;AAC5F,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,cAAc,CAAU,CAAC;AAEpD,wFAAwF;AACxF,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAE5B;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,MAAoC;IACjE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,IAAI,iBAAiB;YAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACnF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,YAAY,CAAC,MAAe,OAAO,CAAC,GAAG;IACrD,OAAO,cAAc,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,OAAyB;IACtE,IAAI,QAAQ,GAAG,OAAO,CAAC;IACvB,KAAK,MAAM,MAAM,IAAI,OAAO;QAAE,QAAQ,GAAG,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACnF,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc,EAAE,OAAyB,EAAE,KAAK,GAAG,CAAC;IAC/E,8FAA8F;IAC9F,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,SAAS,CAAC;IACjC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,YAAY,CAAC,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;IAClF,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;IAC7F,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CACxG,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/lib/repository-files.d.ts

@@ -0,0 +1,50 @@
+import type { WriteFileInput } from './gitlab-client.js';
+/** The envelope GitLab answers a file read with; `content` is base64 unless it says otherwise. */
+export interface FilePayload {
+    readonly file_name?: string;
+    readonly file_path?: string;
+    readonly size?: number;
+    readonly encoding?: string;
+    readonly content?: string;
+    readonly ref?: string;
+    readonly blob_id?: string;
+    readonly commit_id?: string;
+    readonly last_commit_id?: string;
+}
+/** A decoded file, and whether decoding produced something a terminal can show. */
+export interface DecodedFile {
+    readonly text: string;
+    readonly bytes: number;
+    /**
+     * False when the file is binary. A caller then has the bytes but must not print them: a PNG
+     * written to a terminal emits escape sequences, and written to an agent's context it is noise
+     * that can carry an instruction.
+     */
+    readonly printable: boolean;
+}
+/**
+ * Decodes the base64 body of a file read.
+ *
+ * GitLab has answered with `encoding: "text"` on some self-managed versions, so the encoding is
+ * honoured rather than assumed — decoding plain text as base64 yields silent garbage, which is
+ * exactly the failure a user cannot diagnose from the output.
+ */
+export declare function decodeFileContent(payload: FilePayload): DecodedFile;
+export interface FileWriteInput {
+    readonly branch?: string;
+    readonly content?: string;
+    readonly contentFile?: string;
+    readonly message?: string;
+    readonly authorEmail?: string;
+    readonly authorName?: string;
+    readonly startBranch?: string;
+    readonly lastCommitId?: string;
+}
+/**
+ * Turns the flags (or tool inputs) of a file write into the client's input.
+ *
+ * Content comes from either a literal or a file, never both, and the branch and commit message
+ * are required by GitLab — checked here so the refusal names the missing flag instead of arriving
+ * as a 400 whose body says `branch is missing`.
+ */
+export declare function buildFileWrite(input: FileWriteInput): WriteFileInput;

package/lib/repository-files.js

@@ -0,0 +1,70 @@
+/*
+ * 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 { Buffer } from 'node:buffer';
+import { ConfigError } from './errors.js';
+import { readTextFile } from './json-input.js';
+/** A NUL byte does not occur in valid UTF-8 text, and is the cheapest binary tell there is. */
+function looksBinary(text) {
+    return text.includes('\u0000');
+}
+/**
+ * Decodes the base64 body of a file read.
+ *
+ * GitLab has answered with `encoding: "text"` on some self-managed versions, so the encoding is
+ * honoured rather than assumed — decoding plain text as base64 yields silent garbage, which is
+ * exactly the failure a user cannot diagnose from the output.
+ */
+export function decodeFileContent(payload) {
+    const content = payload.content;
+    if (typeof content !== 'string') {
+        throw new ConfigError('The response carried no file content. Check the ref and the file path.');
+    }
+    const buffer = payload.encoding === 'base64' ? Buffer.from(content, 'base64') : Buffer.from(content, 'utf8');
+    const text = buffer.toString('utf8');
+    return { text, bytes: buffer.byteLength, printable: !looksBinary(text) };
+}
+/**
+ * Turns the flags (or tool inputs) of a file write into the client's input.
+ *
+ * Content comes from either a literal or a file, never both, and the branch and commit message
+ * are required by GitLab — checked here so the refusal names the missing flag instead of arriving
+ * as a 400 whose body says `branch is missing`.
+ */
+export function buildFileWrite(input) {
+    if (input.content !== undefined && input.contentFile !== undefined) {
+        throw new ConfigError('Pass --content or --content-file, not both.');
+    }
+    const content = input.content ?? (input.contentFile === undefined ? undefined : readTextFile(input.contentFile, 'Content file'));
+    if (content === undefined) {
+        throw new ConfigError('File content is required: pass --content or --content-file.');
+    }
+    if (input.branch === undefined || input.branch === '') {
+        throw new ConfigError('A branch is required: pass --branch.');
+    }
+    if (input.message === undefined || input.message === '') {
+        throw new ConfigError('A commit message is required: pass --message.');
+    }
+    return {
+        branch: input.branch,
+        content,
+        commitMessage: input.message,
+        authorEmail: input.authorEmail,
+        authorName: input.authorName,
+        startBranch: input.startBranch,
+        lastCommitId: input.lastCommitId,
+    };
+}
+//# sourceMappingURL=repository-files.js.map

package/lib/repository-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository-files.js","sourceRoot":"","sources":["../src/repository-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AA4B/C,+FAA+F;AAC/F,SAAS,WAAW,CAAC,IAAY;IAC/B,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAoB;IACpD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAChC,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,MAAM,IAAI,WAAW,CAAC,wEAAwE,CAAC,CAAC;IAClG,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC7G,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACrC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,EAAE,SAAS,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;AAC3E,CAAC;AAaD;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAqB;IAClD,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACnE,MAAM,IAAI,WAAW,CAAC,6CAA6C,CAAC,CAAC;IACvE,CAAC;IAED,MAAM,OAAO,GACX,KAAK,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC,CAAC;IACnH,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,IAAI,WAAW,CAAC,6DAA6D,CAAC,CAAC;IACvF,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QACtD,MAAM,IAAI,WAAW,CAAC,sCAAsC,CAAC,CAAC;IAChE,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,KAAK,EAAE,EAAE,CAAC;QACxD,MAAM,IAAI,WAAW,CAAC,+CAA+C,CAAC,CAAC;IACzE,CAAC;IAED,OAAO;QACL,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,OAAO;QACP,aAAa,EAAE,KAAK,CAAC,OAAO;QAC5B,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,YAAY,EAAE,KAAK,CAAC,YAAY;KACjC,CAAC;AACJ,CAAC"}

package/lib/search.d.ts

@@ -0,0 +1,20 @@
+import type { SearchScope } from './gitlab-client.js';
+import type { Column } from './output.js';
+import { type Row } from './tables.js';
+/** The scopes every GitLab instance can search without Advanced Search (Elasticsearch) enabled. */
+export declare const BASIC_SCOPES: readonly SearchScope[];
+/**
+ * The scopes that need Advanced Search on the instance. Named so a caller can be told *why* a
+ * scope came back empty: GitLab answers an unsupported scope with an empty list and a 200, which
+ * is indistinguishable from "no matches" unless something says otherwise.
+ */
+export declare const ADVANCED_SCOPES: readonly SearchScope[];
+export declare function needsAdvancedSearch(scope: SearchScope): boolean;
+/**
+ * The columns to render for a search result set.
+ *
+ * Each scope returns a different object — a blob hit has a path and a line number, a user hit has
+ * a username — so one column set for all of them would show an em dash in most cells. The scope
+ * is known before the request, so the renderer picks by scope rather than sniffing the rows.
+ */
+export declare function searchColumns(scope: SearchScope): ReadonlyArray<Column<Row>>;

package/lib/search.js

@@ -0,0 +1,92 @@
+/*
+ * 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 { commitColumns, mergeRequestColumns, projectColumns } from './tables.js';
+/** The scopes every GitLab instance can search without Advanced Search (Elasticsearch) enabled. */
+export const BASIC_SCOPES = ['projects', 'issues', 'merge_requests', 'milestones', 'users'];
+/**
+ * The scopes that need Advanced Search on the instance. Named so a caller can be told *why* a
+ * scope came back empty: GitLab answers an unsupported scope with an empty list and a 200, which
+ * is indistinguishable from "no matches" unless something says otherwise.
+ */
+export const ADVANCED_SCOPES = ['blobs', 'commits', 'wiki_blobs', 'notes', 'snippet_titles'];
+export function needsAdvancedSearch(scope) {
+    return ADVANCED_SCOPES.includes(scope);
+}
+const issueColumns = [
+    { header: 'IID', value: (row) => row.iid },
+    { header: 'STATE', value: (row) => row.state },
+    { header: 'PROJECT', value: (row) => row.project_id },
+    { header: 'TITLE', value: (row) => row.title },
+];
+const blobColumns = [
+    { header: 'PATH', value: (row) => row.path ?? row.filename },
+    { header: 'REF', value: (row) => row.ref },
+    { header: 'LINE', value: (row) => row.startline },
+    { header: 'PROJECT', value: (row) => row.project_id },
+];
+const userColumns = [
+    { header: 'ID', value: (row) => row.id },
+    { header: 'USERNAME', value: (row) => row.username },
+    { header: 'NAME', value: (row) => row.name },
+    { header: 'STATE', value: (row) => row.state },
+];
+const milestoneColumns = [
+    { header: 'IID', value: (row) => row.iid },
+    { header: 'STATE', value: (row) => row.state },
+    { header: 'DUE', value: (row) => row.due_date },
+    { header: 'TITLE', value: (row) => row.title },
+];
+const noteColumns = [
+    { header: 'ID', value: (row) => row.id },
+    { header: 'AUTHOR', value: (row) => row.author?.username },
+    { header: 'BODY', value: (row) => row.body },
+];
+const snippetColumns = [
+    { header: 'ID', value: (row) => row.id },
+    { header: 'TITLE', value: (row) => row.title },
+    { header: 'FILE', value: (row) => row.file_name },
+];
+/**
+ * The columns to render for a search result set.
+ *
+ * Each scope returns a different object — a blob hit has a path and a line number, a user hit has
+ * a username — so one column set for all of them would show an em dash in most cells. The scope
+ * is known before the request, so the renderer picks by scope rather than sniffing the rows.
+ */
+export function searchColumns(scope) {
+    switch (scope) {
+        case 'projects':
+            return projectColumns;
+        case 'issues':
+            return issueColumns;
+        case 'merge_requests':
+            return mergeRequestColumns;
+        case 'milestones':
+            return milestoneColumns;
+        case 'commits':
+            return commitColumns;
+        case 'blobs':
+        case 'wiki_blobs':
+            return blobColumns;
+        case 'notes':
+            return noteColumns;
+        case 'users':
+            return userColumns;
+        case 'snippet_titles':
+            return snippetColumns;
+    }
+}
+//# sourceMappingURL=search.js.map

package/lib/search.js.map

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

package/lib/tables.d.ts

@@ -0,0 +1,21 @@
+import type { Column } from './output.js';
+/**
+ * The column sets each list command renders.
+ *
+ * They live here, in core, rather than on the commands for the same reason the operations do:
+ * the MCP server's tool descriptions quote what a list actually contains, and a column set that
+ * only the CLI knew about would drift from that description with nothing to catch it. Every row
+ * type is `Record<string, unknown>` because these are raw GitLab payloads — the API adds fields
+ * between releases, and typing them exhaustively would make an added field a compile error
+ * rather than a non-event.
+ */
+export type Row = Record<string, unknown>;
+export declare const projectColumns: ReadonlyArray<Column<Row>>;
+export declare const branchColumns: ReadonlyArray<Column<Row>>;
+export declare const tagColumns: ReadonlyArray<Column<Row>>;
+export declare const commitColumns: ReadonlyArray<Column<Row>>;
+export declare const mergeRequestColumns: ReadonlyArray<Column<Row>>;
+export declare const jobColumns: ReadonlyArray<Column<Row>>;
+export declare const variableColumns: ReadonlyArray<Column<Row>>;
+export declare const environmentColumns: ReadonlyArray<Column<Row>>;
+export declare const releaseColumns: ReadonlyArray<Column<Row>>;

package/lib/tables.js

@@ -0,0 +1,105 @@
+/*
+ * 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.
+ */
+/** Reads a nested field without asserting a shape on server JSON. */
+function at(row, ...path) {
+    let cursor = row;
+    for (const key of path) {
+        if (typeof cursor !== 'object' || cursor === null)
+            return undefined;
+        cursor = cursor[key];
+    }
+    return cursor;
+}
+/**
+ * Renders a boolean API field.
+ *
+ * Deliberately 'no' rather than a blank: the renderer shows a missing value as an em dash, and a
+ * branch that is genuinely not merged is not a missing value. Anything that is not a boolean is
+ * left undefined so it renders as the em dash, which is then honest — the API did not say.
+ */
+function flag(value) {
+    return typeof value === 'boolean' ? (value ? 'yes' : 'no') : undefined;
+}
+/** Trims an ISO timestamp to the date, which is what a list is actually scanned for. */
+function day(value) {
+    return typeof value === 'string' && value.length >= 10 ? value.slice(0, 10) : value;
+}
+export const projectColumns = [
+    { header: 'ID', value: (row) => row.id },
+    { header: 'PATH', value: (row) => row.path_with_namespace },
+    { header: 'VISIBILITY', value: (row) => row.visibility },
+    { header: 'DEFAULT BRANCH', value: (row) => row.default_branch },
+    { header: 'LAST ACTIVITY', value: (row) => day(row.last_activity_at) },
+];
+export const branchColumns = [
+    { header: 'NAME', value: (row) => row.name },
+    { header: 'DEFAULT', value: (row) => flag(row.default) },
+    { header: 'PROTECTED', value: (row) => flag(row.protected) },
+    { header: 'MERGED', value: (row) => flag(row.merged) },
+    { header: 'COMMIT', value: (row) => at(row, 'commit', 'short_id') },
+    { header: 'TITLE', value: (row) => at(row, 'commit', 'title') },
+];
+export const tagColumns = [
+    { header: 'NAME', value: (row) => row.name },
+    { header: 'COMMIT', value: (row) => at(row, 'commit', 'short_id') },
+    { header: 'CREATED', value: (row) => day(at(row, 'commit', 'created_at')) },
+    { header: 'MESSAGE', value: (row) => row.message },
+];
+export const commitColumns = [
+    { header: 'SHA', value: (row) => row.short_id },
+    { header: 'DATE', value: (row) => day(row.created_at) },
+    { header: 'AUTHOR', value: (row) => row.author_name },
+    { header: 'TITLE', value: (row) => row.title },
+];
+export const mergeRequestColumns = [
+    { header: 'IID', value: (row) => row.iid },
+    { header: 'STATE', value: (row) => row.state },
+    { header: 'SOURCE', value: (row) => row.source_branch },
+    { header: 'TARGET', value: (row) => row.target_branch },
+    { header: 'AUTHOR', value: (row) => at(row, 'author', 'username') },
+    { header: 'UPDATED', value: (row) => day(row.updated_at) },
+    { header: 'TITLE', value: (row) => row.title },
+];
+export const jobColumns = [
+    { header: 'ID', value: (row) => row.id },
+    { header: 'STATUS', value: (row) => row.status },
+    { header: 'STAGE', value: (row) => row.stage },
+    { header: 'NAME', value: (row) => row.name },
+    { header: 'REF', value: (row) => row.ref },
+    { header: 'PIPELINE', value: (row) => at(row, 'pipeline', 'id') },
+];
+export const variableColumns = [
+    { header: 'KEY', value: (row) => row.key },
+    { header: 'SCOPE', value: (row) => row.environment_scope },
+    { header: 'TYPE', value: (row) => row.variable_type },
+    { header: 'PROTECTED', value: (row) => flag(row.protected) },
+    { header: 'MASKED', value: (row) => flag(row.masked) },
+    { header: 'VALUE', value: (row) => row.value },
+];
+export const environmentColumns = [
+    { header: 'ID', value: (row) => row.id },
+    { header: 'NAME', value: (row) => row.name },
+    { header: 'STATE', value: (row) => row.state },
+    { header: 'TIER', value: (row) => row.tier },
+    { header: 'EXTERNAL URL', value: (row) => row.external_url },
+];
+export const releaseColumns = [
+    { header: 'TAG', value: (row) => row.tag_name },
+    { header: 'NAME', value: (row) => row.name },
+    { header: 'RELEASED', value: (row) => day(row.released_at) },
+    { header: 'AUTHOR', value: (row) => at(row, 'author', 'username') },
+];
+//# sourceMappingURL=tables.js.map

package/lib/tables.js.map

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

package/lib/testing.d.ts

@@ -0,0 +1,16 @@
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+export interface RecordedRequest {
+    method: string;
+    url: string;
+    body: string;
+}
+export type RouteHandler = (request: IncomingMessage, response: ServerResponse, body: string) => void;
+export interface TestServer {
+    baseUrl: string;
+    requests: RecordedRequest[];
+    route: (pathname: string, handler: RouteHandler) => void;
+    close: () => Promise<void>;
+}
+export declare function respondJson(response: ServerResponse, status: number, payload: unknown, headers?: Record<string, string>): void;
+/** Tiny local HTTP server: register handlers per pathname, and every request gets recorded. */
+export declare function startTestServer(): Promise<TestServer>;

package/lib/testing.js

@@ -0,0 +1,63 @@
+/*
+ * 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 { createServer } from 'node:http';
+export function respondJson(response, status, payload, headers = {}) {
+    response.writeHead(status, { 'content-type': 'application/json', ...headers });
+    response.end(JSON.stringify(payload));
+}
+/** Tiny local HTTP server: register handlers per pathname, and every request gets recorded. */
+export async function startTestServer() {
+    const routes = new Map();
+    const requests = [];
+    const server = createServer((request, response) => {
+        const chunks = [];
+        request.on('data', (chunk) => chunks.push(chunk));
+        request.on('end', () => {
+            const body = Buffer.concat(chunks).toString('utf8');
+            const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+            requests.push({ method: request.method ?? '', url: request.url ?? '', body });
+            const handler = routes.get(url.pathname);
+            if (handler) {
+                handler(request, response, body);
+            }
+            else {
+                respondJson(response, 404, { error: `no route for ${url.pathname}` });
+            }
+        });
+    });
+    const baseUrl = await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            if (!address || typeof address === 'string') {
+                reject(new Error('failed to allocate a port'));
+                return;
+            }
+            resolve(`http://127.0.0.1:${address.port}`);
+        });
+    });
+    return {
+        baseUrl,
+        requests,
+        route: (pathname, handler) => {
+            routes.set(pathname, handler);
+        },
+        close: () => new Promise((resolve, reject) => {
+            server.close((error) => (error ? reject(error) : resolve()));
+        }),
+    };
+}
+//# sourceMappingURL=testing.js.map