@molecule/api-git-provider-smolforge 1.0.2

package/README.md

@@ -0,0 +1,86 @@
+<!--
+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:27.110Z
+-->
+
+# @molecule/api-git-provider-smolforge
+
+> **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-smolforge` — 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-smolforge'
+
+registerGitProvider(provider)
+```
+
+## Type
+
+`provider`
+
+## Installation
+
+```bash
+npm install @molecule/api-git-provider-smolforge @molecule/api-git-provider @molecule/api-http
+```
+
+## API
+
+### Constants
+
+#### `provider`
+
+The SmolForge provider.
+
+The first bond in this category with no OAuth: SmolForge's
+`GET /api/auth/login-options` reports a single `password` method, and there
+are no authorize/token endpoints. Git access is via a personal access token
+the user mints, which is why `auth.kind` is `pat`.
+
+```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-smolforge'
+
+export function setupGitProviderSmolforge(): 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-smolforge` — 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-smolforge'
+ *
+ * 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-smolforge` — 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-smolforge'
+ *
+ * registerGitProvider(provider)
+ * ```
+ *
+ * @module
+ */
+export * from './provider.js';

package/dist/provider.d.ts

@@ -0,0 +1,16 @@
+/**
+ * SmolForge git-hosting provider.
+ *
+ * @module
+ */
+import type { GitProvider } from '@molecule/api-git-provider';
+/**
+ * The SmolForge provider.
+ *
+ * The first bond in this category with no OAuth: SmolForge's
+ * `GET /api/auth/login-options` reports a single `password` method, and there
+ * are no authorize/token endpoints. Git access is via a personal access token
+ * the user mints, which is why `auth.kind` is `pat`.
+ */
+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;AAqDnC;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,EAAE,WA8DtB,CAAA"}

package/dist/provider.js

@@ -0,0 +1,101 @@
+/**
+ * SmolForge git-hosting provider.
+ *
+ * @module
+ */
+/**
+ * Normalize SmolForge's repository shape.
+ *
+ * Two fields have to be DERIVED rather than read, because the API does not
+ * return them:
+ *   - `fullName` — composed from `owner.username` and `name`.
+ *   - `url` — composed as `https://<host>/<owner>/<name>.git`, the documented
+ *     Git Smart HTTP remote. Every other provider hands back a clone URL.
+ *
+ * That is why `host` is a parameter here: without it there is no clone URL at
+ * all, and emitting a repository a consumer cannot clone is worse than omitting
+ * it, since the failure surfaces later during the clone.
+ *
+ * @param repo - SmolForge's repository JSON.
+ * @param host - The instance host, needed to build the clone URL.
+ * @returns The normalized repository, or null when unusable.
+ */
+const normalize = (repo, host) => {
+    const owner = repo.owner?.username;
+    if (!owner || !repo.name)
+        return null;
+    return {
+        fullName: `${owner}/${repo.name}`,
+        url: `https://${host}/${owner}/${repo.name}.git`,
+        private: typeof repo.visibility === 'string' ? repo.visibility !== 'public' : null,
+        defaultBranch: repo.default_branch ?? null,
+        // Not reported by the API. Null is the honest answer — a 0 would read as an
+        // empty repository and could gate an import on a size check that never had
+        // real data behind it.
+        sizeKb: null,
+        updatedAt: repo.updated_at ?? repo.created_at ?? null,
+        description: repo.description ?? null,
+    };
+};
+/**
+ * The SmolForge provider.
+ *
+ * The first bond in this category with no OAuth: SmolForge's
+ * `GET /api/auth/login-options` reports a single `password` method, and there
+ * are no authorize/token endpoints. Git access is via a personal access token
+ * the user mints, which is why `auth.kind` is `pat`.
+ */
+export const provider = {
+    id: 'smolforge',
+    label: 'SmolForge',
+    defaultHost: 'forge.smol.ai',
+    auth: {
+        kind: 'pat',
+        tokensUrl: 'https://forge.smol.ai/settings/tokens',
+    },
+    // NULL, not a literal: SmolForge expects the user's own Forge username as the
+    // basic-auth username, with the PAT as the password. A consumer must
+    // substitute the connected account's username here.
+    basicAuthUsername: null,
+    apiBaseForHost(host) {
+        return `https://${host}/api`;
+    },
+    apiHeaders(token) {
+        const headers = {
+            'user-agent': 'molecule-dev',
+            accept: 'application/json',
+        };
+        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}/repos?per_page=${input.perPage}&page=${input.page}`, { headers: this.apiHeaders(input.token), timeout: 15_000 });
+        // Wrapped in `repositories`, unlike the bare arrays GitHub/GitLab/Gitea
+        // return — reading `response.data` as an array here yields silently empty
+        // pages rather than an error.
+        return (response.data?.repositories ?? []).flatMap((repo) => {
+            const normalized = normalize(repo, input.host);
+            return normalized ? [normalized] : [];
+        });
+    },
+    async getRepository(input) {
+        const { get } = await import('@molecule/api-http');
+        const base = this.apiBaseForHost(input.host);
+        try {
+            const response = await get(`${base}/repos/${input.path}`, { headers: this.apiHeaders(input.token), timeout: 15_000 });
+            // Single lookups are wrapped too; fall back to the bare object so a shape
+            // change in either direction still resolves rather than returning null.
+            const repo = response.data?.repository ?? response.data;
+            return repo ? normalize(repo, input.host) : 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-smolforge",
+  "version": "1.0.2",
+  "description": "Git hosting provider for SmolForge (forge.smol.ai) — 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",
+    "smolforge"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/bonds/git-provider/smolforge"
+  },
+  "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"
+  }
+}