forges 0.0.0 → 0.1.0

package/dist/env.d.mts

@@ -0,0 +1,46 @@
+import { n as FetchLike } from "./fetch-D4pSRvvA.mjs";
+import { _ as Forges, g as ForgeProviderFactory } from "./provider-CoZ7cCxp.mjs";
+//#region src/env.d.ts
+/** One set of variables that `providersFromEnv()` reads, and the provider factory it made from them. */
+export interface EnvProvider {
+  forge: string;
+  /** The part after the field, for example `WORK` in `FORGES_GITHUB_TOKEN_WORK`. Empty for the unsuffixed set. */
+  suffix: string;
+  /** The factory to pass to `createForges()`. Missing when the set was skipped. */
+  factory?: ForgeProviderFactory;
+  /** Instance host the factory's providers report, when the set was not skipped. */
+  instance?: string;
+  /** Why the set was skipped, when it was. Never contains a credential. */
+  skipped?: string;
+  /** `DEMO_REPO`: a repository to show, as `owner/name`. GitLab owners may contain slashes. */
+  demoRepo?: {
+    owner: string;
+    name: string;
+  };
+}
+/** Options for `providersFromEnv()` and `forgesFromEnv()`. */
+export interface FromEnvOptions {
+  /** Passed to every provider, for tests and runtimes without a global `fetch`. */
+  fetch?: FetchLike;
+}
+/**
+ * Reads provider sets from `FORGES_<KIND>_<FIELD>[_<SUFFIX>]` variables. A
+ * suffix starts another instance of the same forge.
+ * @param env The variables to read, such as `process.env`.
+ * @param options Options that every provider is created with.
+ */
+export declare function providersFromEnv(env: Record<string, string | undefined>, options?: FromEnvOptions): EnvProvider[];
+/**
+ * Builds `Forges` from environment variables; see {@link providersFromEnv}.
+ * @param env The variables to read, such as `process.env`.
+ * @param options Options that every provider is created with.
+ * @example
+ * ```ts
+ * import { forgesFromEnv } from 'forges/env'
+ *
+ * // FORGES_GITHUB_TOKEN=... FORGES_GITLAB_TOKEN=...
+ * const forges = forgesFromEnv(process.env)
+ * ```
+ */
+export declare function forgesFromEnv(env: Record<string, string | undefined>, options?: FromEnvOptions): Forges;
+//#endregion

package/dist/env.mjs

@@ -0,0 +1,283 @@
+import { n as azureDevOps } from "./azure-devops-DwQvL4TV.mjs";
+import { t as bitbucket } from "./bitbucket-CpcfJlYi.mjs";
+import { n as cursorOrigin } from "./cursor-origin-BhqYx2oW.mjs";
+import { n as forgejo } from "./forgejo-BCefbHUN.mjs";
+import { gitea } from "./gitea/index.mjs";
+import { t as gitee } from "./gitee-CA-f7Rs8.mjs";
+import { t as github } from "./github-B0umL8_f.mjs";
+import { t as gitlab } from "./gitlab-Bsr__Z0C.mjs";
+import { t as createForges } from "./provider-Ed1YhkQN.mjs";
+import { t as pushin } from "./pushin-CkxgJ2cU.mjs";
+import { t as tangled } from "./tangled-ChdPmiv-.mjs";
+//#region src/env.ts
+const KINDS = [
+	"GITHUB",
+	"GITLAB",
+	"BITBUCKET",
+	"FORGEJO",
+	"GITEA",
+	"TANGLED",
+	"CURSOR_ORIGIN",
+	"GITEE",
+	"AZURE_DEVOPS",
+	"PUSHIN"
+];
+/** Field names, longest first so `INSTANCE_VERSION` is not read as `INSTANCE` with suffix `VERSION`. */
+const FIELDS = [
+	"NOTIFICATIONS_URL",
+	"INSTANCE_VERSION",
+	"INSTALLATION_ID",
+	"WEBHOOK_SECRET",
+	"PRIVATE_KEY",
+	"ORGANIZATION",
+	"IDENTIFIER",
+	"READ_ONLY",
+	"BASE_URL",
+	"PASSWORD",
+	"USERNAME",
+	"DEMO_REPO",
+	"INSTANCE",
+	"API_URL",
+	"ENABLED",
+	"APP_ID",
+	"TOKEN",
+	"PDS"
+];
+function parseRepo(value) {
+	const path = value?.replace(/^@/, "");
+	const slash = path?.lastIndexOf("/") ?? -1;
+	return path && slash > 0 ? {
+		owner: path.slice(0, slash),
+		name: path.slice(slash + 1)
+	} : void 0;
+}
+/**
+* Reads provider sets from `FORGES_<KIND>_<FIELD>[_<SUFFIX>]` variables. A
+* suffix starts another instance of the same forge.
+* @param env The variables to read, such as `process.env`.
+* @param options Options that every provider is created with.
+*/
+function providersFromEnv(env, options = {}) {
+	const sets = /* @__PURE__ */ new Map();
+	for (const [key, value] of Object.entries(env)) {
+		if (!key.startsWith("FORGES_") || value === void 0 || value === "") continue;
+		const rest = key.slice(7);
+		const kind = KINDS.find((candidate) => rest === candidate || rest.startsWith(`${candidate}_`));
+		if (!kind) continue;
+		const tail = rest.slice(kind.length + 1);
+		const fieldName = FIELDS.find((candidate) => tail === candidate || tail.startsWith(`${candidate}_`));
+		if (!fieldName) continue;
+		const suffix = tail.slice(fieldName.length + 1);
+		const id = `${kind}:${suffix}`;
+		const set = sets.get(id) ?? {
+			kind,
+			suffix,
+			fields: {}
+		};
+		set.fields[fieldName] = value;
+		sets.set(id, set);
+	}
+	return [...sets.values()].map((set) => withInstance(fromFields(set.kind, set.suffix, set.fields, options)));
+}
+/** Adds `instance`, creating a provider only when it is first read. */
+function withInstance(entry) {
+	const { factory } = entry;
+	if (!factory) return entry;
+	let instance;
+	return Object.defineProperty({ ...entry }, "instance", {
+		enumerable: true,
+		configurable: true,
+		get: () => instance ??= factory.create().instance,
+		set: (value) => {
+			instance = value;
+		}
+	});
+}
+function fromFields(kind, suffix, fields, options) {
+	const base = {
+		...options.fetch ? { fetch: options.fetch } : {},
+		...fields.BASE_URL ? { baseUrl: fields.BASE_URL } : {},
+		...fields.WEBHOOK_SECRET ? { webhookSecret: fields.WEBHOOK_SECRET } : {},
+		...fields.INSTANCE ? { instance: fields.INSTANCE } : {},
+		...fields.INSTANCE_VERSION ? { instanceVersion: fields.INSTANCE_VERSION } : {},
+		...isOn(fields.READ_ONLY) ? { readOnly: true } : {}
+	};
+	const demoRepo = parseRepo(fields.DEMO_REPO);
+	const anonymous = isOn(fields.ENABLED) || Boolean(demoRepo);
+	const entry = {
+		forge: kind.toLowerCase().replaceAll("_", "-"),
+		suffix,
+		...demoRepo ? { demoRepo } : {}
+	};
+	if (fields.ENABLED === "0" || fields.ENABLED === "false") return {
+		...entry,
+		skipped: "ENABLED is off"
+	};
+	switch (kind) {
+		case "GITHUB":
+			if (fields.APP_ID && fields.PRIVATE_KEY) return {
+				...entry,
+				factory: github({
+					...base,
+					auth: {
+						type: "app",
+						appId: fields.APP_ID,
+						privateKey: fields.PRIVATE_KEY.replaceAll("\\n", "\n"),
+						installationId: fields.INSTALLATION_ID
+					}
+				})
+			};
+			if (fields.TOKEN || anonymous) return {
+				...entry,
+				factory: github({
+					...base,
+					...fields.TOKEN ? { auth: {
+						type: "token",
+						token: fields.TOKEN
+					} } : {}
+				})
+			};
+			return {
+				...entry,
+				skipped: "needs TOKEN, or APP_ID and PRIVATE_KEY, or ENABLED for anonymous reads"
+			};
+		case "BITBUCKET":
+			if (fields.USERNAME && fields.PASSWORD) return {
+				...entry,
+				factory: bitbucket({
+					...base,
+					auth: {
+						type: "basic",
+						username: fields.USERNAME,
+						password: fields.PASSWORD
+					}
+				})
+			};
+			if (fields.TOKEN || anonymous) return {
+				...entry,
+				factory: bitbucket({
+					...base,
+					...fields.TOKEN ? { auth: {
+						type: "token",
+						token: fields.TOKEN
+					} } : {}
+				})
+			};
+			return {
+				...entry,
+				skipped: "needs TOKEN, or USERNAME and PASSWORD, or ENABLED for anonymous reads"
+			};
+		case "AZURE_DEVOPS": {
+			if (!fields.ORGANIZATION) return {
+				...entry,
+				skipped: "needs ORGANIZATION"
+			};
+			const auth = fields.USERNAME && fields.PASSWORD ? {
+				type: "basic",
+				username: fields.USERNAME,
+				password: fields.PASSWORD
+			} : fields.TOKEN ? {
+				type: "token",
+				token: fields.TOKEN
+			} : void 0;
+			return auth || anonymous ? {
+				...entry,
+				factory: azureDevOps({
+					...base,
+					organization: fields.ORGANIZATION,
+					...auth ? { auth } : {}
+				})
+			} : {
+				...entry,
+				skipped: "needs TOKEN, or USERNAME and PASSWORD, or ENABLED for anonymous reads"
+			};
+		}
+		case "CURSOR_ORIGIN":
+			if (fields.APP_ID && fields.PRIVATE_KEY) return {
+				...entry,
+				factory: cursorOrigin({
+					...base,
+					auth: {
+						type: "app",
+						appId: fields.APP_ID,
+						privateKey: fields.PRIVATE_KEY.replaceAll("\\n", "\n"),
+						installationId: fields.INSTALLATION_ID
+					}
+				})
+			};
+			if (fields.TOKEN) return {
+				...entry,
+				factory: cursorOrigin({
+					...base,
+					auth: {
+						type: "token",
+						token: fields.TOKEN
+					}
+				})
+			};
+			return isOn(fields.ENABLED) ? {
+				...entry,
+				factory: cursorOrigin(base)
+			} : {
+				...entry,
+				skipped: "needs TOKEN, or APP_ID and PRIVATE_KEY, or ENABLED for webhooks only"
+			};
+		case "TANGLED": return {
+			...entry,
+			factory: tangled({
+				...base,
+				...fields.API_URL ? { apiUrl: fields.API_URL } : {},
+				...fields.NOTIFICATIONS_URL ? { notificationsUrl: fields.NOTIFICATIONS_URL } : {},
+				...fields.IDENTIFIER && fields.PASSWORD ? { auth: {
+					type: "app_password",
+					identifier: fields.IDENTIFIER,
+					password: fields.PASSWORD,
+					...fields.PDS ? { pds: fields.PDS } : {}
+				} } : {}
+			})
+		};
+		default: {
+			if (!fields.TOKEN && !anonymous) return {
+				...entry,
+				skipped: "needs TOKEN, or ENABLED for anonymous reads"
+			};
+			const create = {
+				GITLAB: gitlab,
+				FORGEJO: forgejo,
+				GITEA: gitea,
+				GITEE: gitee,
+				PUSHIN: pushin
+			}[kind];
+			return {
+				...entry,
+				factory: create({
+					...base,
+					...fields.TOKEN ? { auth: {
+						type: "token",
+						token: fields.TOKEN
+					} } : {}
+				})
+			};
+		}
+	}
+}
+function isOn(value) {
+	return value === "1" || value === "true";
+}
+/**
+* Builds `Forges` from environment variables; see {@link providersFromEnv}.
+* @param env The variables to read, such as `process.env`.
+* @param options Options that every provider is created with.
+* @example
+* ```ts
+* import { forgesFromEnv } from 'forges/env'
+*
+* // FORGES_GITHUB_TOKEN=... FORGES_GITLAB_TOKEN=...
+* const forges = forgesFromEnv(process.env)
+* ```
+*/
+function forgesFromEnv(env, options = {}) {
+	return createForges(providersFromEnv(env, options).flatMap((entry) => entry.factory ? [entry.factory] : []));
+}
+//#endregion
+export { forgesFromEnv, providersFromEnv };

package/dist/fake/index.d.mts

@@ -0,0 +1,227 @@
+import { Bt as Notification, Ct as ForgeEvent, Et as ForgeKind, Fn as Thread, G as Check, Ht as NotificationReason, J as CheckState, Ln as ThreadKind, Q as CiRun, St as FileStatus, Vn as ThreadState, W as ChangedFile, X as CiJob, Yn as Webhook, Zt as Reaction, at as Comment, en as Release, gn as Review, jn as SubscriptionState, on as Repo, st as Commit } from "../fetch-D4pSRvvA.mjs";
+import { f as ForgeCapabilities, g as ForgeProviderFactory, h as ForgeProvider, m as ForgeOptionsBase, q as ForgeVerb } from "../provider-CoZ7cCxp.mjs";
+import { f as VerbKind, u as SupportInput } from "../define-B2_4ob2i.mjs";
+//#region src/fake/index.d.ts
+/** A repository to seed, as `owner/name` plus whatever the test cares about. */
+export interface FakeRepoSeed {
+  /** The repository as `owner/name`. */
+  repo: string;
+  description?: string;
+  /**
+   * The default branch.
+   * @default main
+   */
+  defaultBranch?: string;
+  /**
+   * @default public
+   */
+  visibility?: Repo["visibility"];
+  /** Names of the labels that the repository defines. */
+  labels?: string[];
+}
+/** An issue, pull request or discussion to seed. */
+export interface FakeThreadSeed {
+  /** The repository as `owner/name`. */
+  repo: string;
+  kind: Exclude<ThreadKind, "other" | "commit">;
+  /** Defaults to the next free number in the repository. */
+  number?: number;
+  title: string;
+  body?: string;
+  /**
+   * @default open
+   */
+  state?: ThreadState;
+  isDraft?: boolean;
+  /** The login of the author. Defaults to the viewer. */
+  author?: string;
+  labels?: string[];
+  assignees?: string[];
+  comments?: Array<{
+    body: string;
+    author?: string;
+  }>;
+  checks?: Array<{
+    name: string;
+    state: CheckState;
+  }>;
+  /** Files the pull request changes. */
+  files?: Array<{
+    path: string;
+    status?: FileStatus;
+    additions?: number;
+    deletions?: number;
+    patch?: string;
+  }>;
+  /** Shas of seeded commits on the pull request. */
+  commits?: string[];
+}
+/** A CI run to seed, with its jobs and their logs. */
+export interface FakeRunSeed {
+  /** The repository as `owner/name`. */
+  repo: string;
+  name: string;
+  state?: CheckState;
+  branch?: string;
+  sha?: string;
+  jobs?: Array<{
+    name: string;
+    state?: CheckState;
+    log?: string;
+  }>;
+}
+/** A file to seed into a repository, at `ref` or on every ref. */
+export interface FakeFileSeed {
+  /** The repository as `owner/name`. */
+  repo: string;
+  path: string;
+  /** Text, or bytes for a binary file. */
+  content: string | Uint8Array;
+  /** Branch, tag or sha the file exists at. Defaults to every ref. */
+  ref?: string;
+}
+/** A commit to seed, with the files it changed. */
+export interface FakeCommitSeed {
+  /** The repository as `owner/name`. */
+  repo: string;
+  sha: string;
+  message: string;
+  author?: string;
+  parents?: string[];
+  committedAt?: Date;
+  files?: Array<{
+    path: string;
+    status?: FileStatus;
+    additions?: number;
+    deletions?: number;
+    patch?: string;
+  }>;
+}
+/** A notification to seed, for an issue or pull request that is seeded as well. */
+export interface FakeNotificationSeed {
+  /** The repository as `owner/name`. */
+  repo: string;
+  /** The number of the thread the notification is about. */
+  number: number;
+  /** Why the viewer got the notification. */
+  reason?: NotificationReason;
+  /**
+   * @default true
+   */
+  unread?: boolean;
+}
+/** A release to seed. */
+export interface FakeReleaseSeed {
+  /** The repository as `owner/name`. */
+  repo: string;
+  tag: string;
+  name?: string;
+  body?: string;
+  isDraft?: boolean;
+  isPrerelease?: boolean;
+  /** The release is immutable, so its tag and target cannot change. */
+  immutable?: boolean;
+  publishedAt?: Date;
+  assets?: Array<{
+    name: string;
+    content: string | Uint8Array;
+    contentType?: string;
+  }>;
+}
+/** The data a fake forge starts with. */
+export interface FakeSeed {
+  repos?: FakeRepoSeed[];
+  files?: FakeFileSeed[];
+  commits?: FakeCommitSeed[];
+  runs?: FakeRunSeed[];
+  threads?: FakeThreadSeed[];
+  notifications?: FakeNotificationSeed[];
+  releases?: FakeReleaseSeed[];
+}
+/** Support for one verb: a level, or a level per thread kind for per-kind verbs. */
+export type FakeSupport = SupportInput | Partial<Record<VerbKind, SupportInput>>;
+/** Options for `fake()`. */
+export interface FakeOptions extends Omit<ForgeOptionsBase, "fetch"> {
+  /**
+   * @default fake
+   */
+  forge?: ForgeKind;
+  /**
+   * Login of the authenticated account; authors every write.
+   * @default fake-user
+   */
+  viewer?: string;
+  seed?: FakeSeed;
+  /** Overrides the default support of individual verbs. */
+  support?: Partial<Record<ForgeVerb, FakeSupport>>;
+  /** Support to copy from a real provider, such as `github().create().capabilities`. `support` wins where both set a verb. */
+  capabilities?: ForgeCapabilities;
+}
+interface FakeRunState {
+  run: CiRun;
+  jobs: Array<{
+    job: CiJob;
+    log: string;
+  }>;
+}
+interface FakeThreadState {
+  thread: Thread;
+  files: ChangedFile[];
+  commits: string[];
+  comments: Comment[];
+  /** Reactions on the thread, keyed by comment id, with `''` for the thread itself. */
+  reactions: Map<string, Reaction[]>;
+  checks: Check[];
+  reviews: Review[];
+  subscription: SubscriptionState;
+}
+/** The in-memory state behind a fake forge. Mutate it to set up a test, read it to assert. */
+export interface FakeStore {
+  /** Every repository with its threads, releases, runs, files and commits, keyed by `owner/name`. */
+  repos: Map<string, {
+    repo: Repo;
+    labels: string[];
+    threads: Map<string, FakeThreadState>;
+    releases: Release[];
+    statuses: Map<string, Check[]>;
+    runs: FakeRunState[];
+    /** Seeded file bytes, keyed by `<ref>:<path>`, with `*` for a file on every ref. */
+    files: Map<string, Uint8Array>;
+    commits: Commit[];
+    /** Seeded release asset bytes, keyed by `<releaseId>:<assetName>`. */
+    assets: Map<string, Uint8Array>;
+  }>;
+  notifications: Notification[];
+  /** Every event a write produced, in order. */
+  events: ForgeEvent[];
+  /** Registered webhooks. Secrets are held separately and never readable. */
+  webhooks: Webhook[];
+}
+/** What `fake()` returns: a provider factory that also exposes the store. */
+export interface FakeForgeFactory extends ForgeProviderFactory<ForgeProvider> {
+  /** The in-memory state of the forge. */
+  readonly store: FakeStore;
+}
+/**
+ * An in-memory forge implementing the whole provider surface, for testing
+ * code that writes. Every write changes `store` and appends a `ForgeEvent`
+ * that `threads.events()` and `sources.subscribe()` return. Webhook
+ * deliveries carry normalised events as JSON, signed as `signDelivery('fake', ...)`
+ * from `forges/testing` signs them.
+ * @param options The data the forge starts with, and the support of individual operations.
+ * @example
+ * ```ts
+ * import { createForges } from 'forges'
+ * import { fake } from 'forges/fake'
+ *
+ * const factory = fake({
+ *   seed: {
+ *     repos: [{ repo: 'acme/widgets' }],
+ *     threads: [{ repo: 'acme/widgets', kind: 'issue', title: 'Broken build' }],
+ *   },
+ * })
+ * const forges = createForges([factory])
+ * ```
+ */
+export declare function fake(options?: FakeOptions): FakeForgeFactory;
+//#endregion