@molecule/api-git-provider-gitlab 1.0.2

package/README.md

@@ -0,0 +1,81 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-08-07T00:19:23.397Z
+-->
+
+# @molecule/api-git-provider-gitlab
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+`@molecule/api-git-provider-gitlab` — a `@molecule/api-git-provider` bond.
+
+Register it with `registerGitProvider(provider)` in `setupBonds()`; the app
+then never names this host. See the core package for the interface and for
+why `basicAuthUsername` may be null.
+
+## Quick Start
+
+```typescript
+import { registerGitProvider } from '@molecule/api-git-provider'
+import { provider } from '@molecule/api-git-provider-gitlab'
+
+registerGitProvider(provider)
+```
+
+## Type
+
+`provider`
+
+## Installation
+
+```bash
+npm install @molecule/api-git-provider-gitlab @molecule/api-git-provider @molecule/api-http
+```
+
+## API
+
+### Constants
+
+#### `provider`
+
+The GitLab provider.
+
+```typescript
+const provider: GitProvider
+```
+
+## Core Interface
+
+Implements `@molecule/api-git-provider` interface.
+
+## Bond Wiring
+
+Setup function to register this provider with the core interface:
+
+```typescript
+import { registerGitProvider } from '@molecule/api-git-provider'
+import { provider } from '@molecule/api-git-provider-gitlab'
+
+export function setupGitProviderGitlab(): void {
+  registerGitProvider(provider)
+}
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/api-git-provider` ^1.0.2
+- `@molecule/api-http` ^1.0.1
+
+### Runtime Dependencies
+
+- `@molecule/api-git-provider`
+- `@molecule/api-http`

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@molecule/api-git-provider-gitlab` — a `@molecule/api-git-provider` bond.
+ *
+ * Register it with `registerGitProvider(provider)` in `setupBonds()`; the app
+ * then never names this host. See the core package for the interface and for
+ * why `basicAuthUsername` may be null.
+ *
+ * @example
+ * ```typescript
+ * import { registerGitProvider } from '@molecule/api-git-provider'
+ * import { provider } from '@molecule/api-git-provider-gitlab'
+ *
+ * registerGitProvider(provider)
+ * ```
+ *
+ * @module
+ */
+export * from './provider.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,cAAc,eAAe,CAAA"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * `@molecule/api-git-provider-gitlab` — a `@molecule/api-git-provider` bond.
+ *
+ * Register it with `registerGitProvider(provider)` in `setupBonds()`; the app
+ * then never names this host. See the core package for the interface and for
+ * why `basicAuthUsername` may be null.
+ *
+ * @example
+ * ```typescript
+ * import { registerGitProvider } from '@molecule/api-git-provider'
+ * import { provider } from '@molecule/api-git-provider-gitlab'
+ *
+ * registerGitProvider(provider)
+ * ```
+ *
+ * @module
+ */
+export * from './provider.js';

package/dist/provider.d.ts

@@ -0,0 +1,9 @@
+/**
+ * GitLab git-hosting provider.
+ *
+ * @module
+ */
+import type { GitProvider } from '@molecule/api-git-provider';
+/** The GitLab provider. */
+export declare const provider: GitProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAEV,WAAW,EAGZ,MAAM,4BAA4B,CAAA;AAwCnC,2BAA2B;AAC3B,eAAO,MAAM,QAAQ,EAAE,WAmEtB,CAAA"}

package/dist/provider.js

@@ -0,0 +1,92 @@
+/**
+ * GitLab git-hosting provider.
+ *
+ * @module
+ */
+/**
+ * Normalize GitLab's project shape.
+ *
+ * Two mappings differ from the obvious:
+ *   - privacy is a `visibility` STRING (`private`/`internal`/`public`), not a
+ *     boolean, and `internal` is not public — treating it as such would show a
+ *     company-internal repo as world-readable in a picker.
+ *   - `statistics.repository_size` is BYTES and only present when the caller
+ *     asked for statistics; the normalized field is KB, so it converts.
+ *
+ * @param project - GitLab's project JSON.
+ * @returns The normalized repository, or null when unusable.
+ */
+const normalize = (project) => {
+    if (!project.path_with_namespace || !project.http_url_to_repo)
+        return null;
+    const bytes = project.statistics?.repository_size;
+    return {
+        fullName: project.path_with_namespace,
+        url: project.http_url_to_repo,
+        private: typeof project.visibility === 'string' ? project.visibility !== 'public' : null,
+        defaultBranch: project.default_branch ?? null,
+        sizeKb: typeof bytes === 'number' ? Math.round(bytes / 1024) : null,
+        updatedAt: project.last_activity_at ?? null,
+        description: project.description ?? null,
+    };
+};
+/** The GitLab provider. */
+export const provider = {
+    id: 'gitlab',
+    label: 'GitLab',
+    defaultHost: 'gitlab.com',
+    auth: {
+        kind: 'oauth',
+        authorizeUrl: 'https://gitlab.com/oauth/authorize',
+        tokenUrl: 'https://gitlab.com/oauth/token',
+        // `write_repository` is the git-over-HTTPS push scope and `read_repository`
+        // pairs with it for fetch. `read_api` is REQUIRED as well, and is the one
+        // that gets forgotten: the *_repository scopes cover only the git protocol,
+        // NOT the REST API, so without it the OAuth flow succeeds and then the repo
+        // picker 403s — a failure that looks nothing like a missing scope. The
+        // registered GitLab application must enable all three.
+        scope: 'read_api read_repository write_repository',
+    },
+    // GitLab expects the literal `oauth2` as the basic-auth username, NOT
+    // GitHub's `x-access-token`. Getting this wrong fails at push time as an
+    // opaque 401, far from the code that chose it.
+    basicAuthUsername: 'oauth2',
+    apiBaseForHost(host) {
+        // Uniform for gitlab.com and self-hosted alike — unlike GitHub, there is no
+        // separate API host.
+        return `https://${host}/api/v4`;
+    },
+    apiHeaders(token) {
+        const headers = { 'user-agent': 'molecule-dev' };
+        if (token)
+            headers.authorization = `Bearer ${token}`;
+        return headers;
+    },
+    async listRepositories(input) {
+        const { get } = await import('@molecule/api-http');
+        const base = this.apiBaseForHost(input.host);
+        const response = await get(`${base}/projects?membership=true&order_by=last_activity_at&sort=desc` +
+            `&per_page=${input.perPage}&page=${input.page}&statistics=true`, { headers: this.apiHeaders(input.token), timeout: 15_000 });
+        return (response.data ?? []).flatMap((project) => {
+            const normalized = normalize(project);
+            return normalized ? [normalized] : [];
+        });
+    },
+    async getRepository(input) {
+        const { get } = await import('@molecule/api-http');
+        const base = this.apiBaseForHost(input.host);
+        try {
+            // GitLab addresses a project by its URL-ENCODED path, not by owner/name
+            // path segments — `group/sub/app` must arrive as one encoded component or
+            // the API reads it as a different route entirely.
+            const response = await get(`${base}/projects/${encodeURIComponent(input.path)}?statistics=true`, { headers: this.apiHeaders(input.token), timeout: 15_000 });
+            return response.data ? normalize(response.data) : null;
+        }
+        catch (error) {
+            const status = error?.response?.status;
+            if (status === 404)
+                return null;
+            throw error;
+        }
+    },
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@molecule/api-git-provider-gitlab",
+  "version": "1.0.2",
+  "description": "Git hosting provider for GitLab (gitlab.com) — OAuth endpoints, token auth shape, repository listing and lookup.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "molecule",
+    "git",
+    "provider",
+    "gitlab"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/bonds/git-provider/gitlab"
+  },
+  "devDependencies": {
+    "@molecule/api-git-provider": "1.0.2",
+    "@molecule/api-http": "1.0.1",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "peerDependencies": {
+    "@molecule/api-git-provider": "^1.0.2",
+    "@molecule/api-http": "^1.0.1"
+  }
+}