@simplysf/simply-gitlab-core 0.2.0 → 0.4.0

package/README.md

@@ -66,6 +66,11 @@ Every export from `src/index.ts` is semver-covered: adding one is a minor or pat
 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.
 
+## Guides
+
+User-facing documentation for the CLI and MCP server built on this package:
+**https://simplysf.github.io/simply-cli/gitlab/**
+
 ## Documentation
 
 - [GitLab client core design](../../docs/design/0001-gitlab-client-core.md)

package/lib/baseline-apply.d.ts

@@ -0,0 +1,35 @@
+import type { BaselinePlan, TargetPlan } from './baseline-plan.js';
+import { type RunOptions } from './baseline-run.js';
+import type { GitLabClient } from './gitlab-client.js';
+/** What executing one target's plan amounted to. */
+export interface TargetResult {
+    readonly path: string;
+    readonly kind: 'project' | 'group';
+    readonly applied: number;
+    /** Set when execution stopped part-way; the actions before it are already applied. */
+    readonly error?: string;
+    /** The section that failed, so a partial application can be described precisely. */
+    readonly failedSection?: string;
+}
+export interface ApplyResult {
+    readonly targets: readonly TargetResult[];
+}
+/**
+ * Executes one target's plan, in the order the sections were planned.
+ *
+ * There is no transaction across GitLab endpoints and this does not pretend otherwise: a failure
+ * part-way leaves the earlier sections applied, and the result says which section stopped it so a
+ * following `plan` can be read against that.
+ */
+export declare function applyTarget(client: GitLabClient, target: TargetPlan): Promise<TargetResult>;
+/**
+ * Executes a whole plan.
+ *
+ * One target failing does not abandon the other forty-nine — that is the default, because a run
+ * that stopped at the twelfth project would leave the operator worse off than one that reported
+ * twelve successes and one failure. `--fail-fast` is there for the systematic problem where the
+ * rest are pointless.
+ */
+export declare function applyPlan(client: GitLabClient, plan: BaselinePlan, options?: RunOptions): Promise<ApplyResult>;
+/** How many targets an apply failed on, for the exit code. */
+export declare function applyFailures(result: ApplyResult): readonly TargetResult[];

package/lib/baseline-apply.js

@@ -0,0 +1,177 @@
+/*
+ * 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 { mapPool, DEFAULT_CONCURRENCY } from './baseline-run.js';
+import { ConfigError } from './errors.js';
+function asRecord(value) {
+    return (typeof value === 'object' && value !== null ? value : {});
+}
+/**
+ * Resolves the name-based references an approval rule carries into the ids the API demands.
+ *
+ * This has to happen here rather than at plan time. A rule scoped to `main` needs that branch's
+ * protection id, and the protected-branches section that creates it runs moments earlier in this
+ * same apply — so at plan time the id does not exist yet.
+ */
+async function resolveRuleReferences(client, ref, body, branches, groups) {
+    const resolved = { ...body };
+    if (branches !== undefined && branches.length > 0) {
+        const protectedBranches = (await client.listProtectedBranches(ref)).items.map(asRecord);
+        const byName = new Map(protectedBranches.map((branch) => [String(branch.name), branch.id]));
+        const ids = [];
+        for (const name of branches) {
+            const id = byName.get(name);
+            if (typeof id !== 'number') {
+                throw new ConfigError(`Approval rule references protected branch "${name}", which is not protected on this project. ` +
+                    'Declare it under protectedBranches so it exists before the rule is written.');
+            }
+            ids.push(id);
+        }
+        resolved.protected_branch_ids = ids;
+    }
+    if (groups !== undefined && groups.length > 0) {
+        const ids = [];
+        /* Each group is one lookup; there are rarely more than a couple on a rule. */
+        /* eslint-disable no-await-in-loop */
+        for (const path of groups) {
+            const group = asRecord(await client.getGroup(path));
+            if (typeof group.id !== 'number') {
+                throw new ConfigError(`Approval rule references group "${path}", which could not be resolved to an id.`);
+            }
+            ids.push(group.id);
+        }
+        /* eslint-enable no-await-in-loop */
+        resolved.group_ids = ids;
+    }
+    return resolved;
+}
+/** Executes one action. Split out so the switch stays exhaustive as actions are added. */
+async function execute(client, target, action) {
+    const ref = target.path;
+    switch (action.kind) {
+        case 'updateProject':
+            await client.updateProject(ref, action.body);
+            return;
+        case 'updateGroup':
+            await client.updateGroup(ref, action.body);
+            return;
+        case 'protectBranch':
+            await client.protectBranch(ref, action.body);
+            return;
+        case 'patchProtectedBranch':
+            await client.patchProtectedBranch(ref, action.name, action.body);
+            return;
+        case 'unprotectBranch':
+            await client.unprotectBranch(ref, action.name);
+            return;
+        case 'protectTag':
+            await client.protectTag(ref, action.body);
+            return;
+        case 'unprotectTag':
+            await client.unprotectTag(ref, action.name);
+            return;
+        case 'updateApprovalSettings':
+            await client.updateApprovalSettings(ref, action.body);
+            return;
+        case 'createApprovalRule': {
+            const groups = Array.isArray(action.body.groups) ? action.body.groups : undefined;
+            const body = await resolveRuleReferences(client, ref, action.body, action.branches, groups);
+            await client.createApprovalRule(ref, body);
+            return;
+        }
+        case 'updateApprovalRule': {
+            const groups = Array.isArray(action.body.groups) ? action.body.groups : undefined;
+            const body = await resolveRuleReferences(client, ref, action.body, action.branches, groups);
+            await client.updateApprovalRule(ref, action.ruleId, body);
+            return;
+        }
+        case 'deleteApprovalRule':
+            await client.deleteApprovalRule(ref, action.ruleId);
+            return;
+        case 'setPushRules':
+            // POST creates the rule set, PUT edits it. Which one applies was decided at plan time from
+            // whether the project already had push rules.
+            if (action.exists)
+                await client.updatePushRules(ref, action.body);
+            else
+                await client.createPushRules(ref, action.body);
+            return;
+        default: {
+            const exhaustive = action;
+            throw new ConfigError(`Unknown action ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
+/**
+ * Executes one target's plan, in the order the sections were planned.
+ *
+ * There is no transaction across GitLab endpoints and this does not pretend otherwise: a failure
+ * part-way leaves the earlier sections applied, and the result says which section stopped it so a
+ * following `plan` can be read against that.
+ */
+export async function applyTarget(client, target) {
+    let applied = 0;
+    for (const section of target.sections) {
+        for (const action of section.actions) {
+            try {
+                // eslint-disable-next-line no-await-in-loop -- order across sections is the contract
+                await execute(client, target, action);
+                applied += 1;
+            }
+            catch (error) {
+                return {
+                    path: target.path,
+                    kind: target.kind,
+                    applied,
+                    failedSection: section.section,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        }
+    }
+    return { path: target.path, kind: target.kind, applied };
+}
+/**
+ * Executes a whole plan.
+ *
+ * One target failing does not abandon the other forty-nine — that is the default, because a run
+ * that stopped at the twelfth project would leave the operator worse off than one that reported
+ * twelve successes and one failure. `--fail-fast` is there for the systematic problem where the
+ * rest are pointless.
+ */
+export async function applyPlan(client, plan, options = {}) {
+    const concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
+    // A target that failed to plan is not applied: acting on a half-read project is how a baseline
+    // makes things worse than it found them.
+    const runnable = plan.targets.filter((target) => target.error === undefined);
+    const unplanned = plan.targets
+        .filter((target) => target.error !== undefined)
+        .map((target) => ({ path: target.path, kind: target.kind, applied: 0, error: target.error }));
+    const groups = runnable.filter((target) => target.kind === 'group');
+    const projects = runnable.filter((target) => target.kind === 'project');
+    const stopAfter = options.failFast === true ? (result) => result.error !== undefined : undefined;
+    // Groups first: a group setting that projects inherit should be in place before the projects are
+    // reconciled against it.
+    const groupResults = await mapPool(groups, concurrency, (target) => applyTarget(client, target), stopAfter);
+    const projectResults = options.failFast === true && groupResults.some((result) => result.error !== undefined)
+        ? []
+        : await mapPool(projects, concurrency, (target) => applyTarget(client, target), stopAfter);
+    return { targets: [...unplanned, ...groupResults, ...projectResults] };
+}
+/** How many targets an apply failed on, for the exit code. */
+export function applyFailures(result) {
+    return result.targets.filter((target) => target.error !== undefined);
+}
+//# sourceMappingURL=baseline-apply.js.map

package/lib/baseline-apply.js.map

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

package/lib/baseline-config.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The baseline configuration file: what a set of projects should have in common.
+ *
+ * Everything here is data. Reading it, diffing against an instance, and converging are three other
+ * modules; this one only turns a file into a validated, merged description of intent — which is
+ * what makes the merge semantics below testable without a server.
+ *
+ * See docs/design/0007-configuration-baselines.md.
+ */
+export interface BaselineConfig {
+    readonly version: 1;
+    readonly targets?: BaselineTargets;
+    readonly group?: GroupDesired;
+    readonly project?: ProjectDesired;
+    readonly overrides?: Readonly<Record<string, TargetOverride>>;
+}
+export interface BaselineTargets {
+    /** Group paths or ids. Expands to every project in the group and its subgroups. */
+    readonly groups?: readonly string[];
+    /** Individual project paths or ids, added to whatever the groups expanded to. */
+    readonly projects?: readonly string[];
+    /** Removed from the union. A trailing `*` drops a whole subtree. */
+    readonly exclude?: readonly string[];
+}
+export interface TargetOverride {
+    readonly project?: ProjectDesired;
+    readonly group?: GroupDesired;
+}
+export interface GroupDesired {
+    readonly settings?: Readonly<Record<string, unknown>>;
+}
+export interface ProjectDesired {
+    readonly settings?: Readonly<Record<string, unknown>>;
+    readonly protectedBranches?: Section;
+    readonly protectedTags?: Section;
+    readonly approvals?: Readonly<Record<string, unknown>>;
+    readonly approvalRules?: Section;
+    readonly pushRules?: Readonly<Record<string, unknown>>;
+    readonly variables?: Section;
+}
+/** An entry in a keyed section. Fields are GitLab's own, so this stays deliberately open. */
+export type Entry = Readonly<Record<string, unknown>>;
+/**
+ * A list section, in either of the two shapes the file accepts: a bare array, or an object that
+ * can also turn on pruning or wholesale replacement.
+ */
+export type Section = readonly Entry[] | SectionObject;
+export interface SectionObject {
+    /** Delete entries that exist on the instance but are not declared here. Off by default. */
+    readonly prune?: boolean;
+    /** Replace the baseline's entries entirely instead of merging into them, in an override. */
+    readonly $replace?: boolean;
+    readonly entries: readonly Entry[];
+}
+/** A section reduced to the three things every consumer needs. */
+export interface NormalizedSection {
+    readonly prune: boolean;
+    readonly replace: boolean;
+    readonly entries: readonly Entry[];
+}
+/** The list sections, in the order `apply` reconciles them. */
+export declare const LIST_SECTIONS: readonly ["protectedBranches", "protectedTags", "approvalRules", "variables"];
+export type ListSection = (typeof LIST_SECTIONS)[number];
+/** The object sections, which merge key by key rather than by entry. */
+export declare const OBJECT_SECTIONS: readonly ["settings", "approvals", "pushRules"];
+/** The identity of one entry, as a string, for keying a map. */
+export declare function entryKey(section: ListSection, entry: Entry): string;
+/** The human-readable identity of one entry, for plan output. */
+export declare function entryLabel(section: ListSection, entry: Entry): string;
+export declare function normalizeSection(section: Section | undefined): NormalizedSection | undefined;
+/**
+ * Validates the parsed file, reporting the JSON path of whatever is wrong.
+ *
+ * Hand-written rather than schema-driven because the error is the product: a caller who wrote
+ * `"targets": {"group": "x"}` needs to be told that the key is `groups` and that it takes an array,
+ * at that path, not that the document failed to match a schema. The published JSON Schema gives an
+ * editor completion and hover text; this is what runs.
+ */
+export declare function validateBaselineConfig(value: unknown, label?: string): BaselineConfig;
+/**
+ * The effective configuration for one project: the baseline with its override merged over it.
+ *
+ * Objects merge key by key. Lists merge by the section's natural key, so an override adjusts one
+ * entry rather than restating the array — unless it sets `$replace`, which swaps the list wholesale
+ * for the project that genuinely needs different rules rather than adjusted ones.
+ */
+export declare function mergeProjectDesired(base?: ProjectDesired, override?: ProjectDesired): ProjectDesired;
+export declare function mergeGroupDesired(base?: GroupDesired, override?: GroupDesired): GroupDesired;
+/** The effective project configuration for one path, baseline merged with any override for it. */
+export declare function effectiveProject(config: BaselineConfig, path: string): ProjectDesired;
+/** The effective group configuration for one path. */
+export declare function effectiveGroup(config: BaselineConfig, path: string): GroupDesired;
+/**
+ * Reads and validates a baseline config file.
+ *
+ * A parse failure reports only the position, never the parser's snippet of the content — the same
+ * rule the rest of this package follows, because a caller can name any path and the snippet would
+ * echo the first bytes of whatever file that was.
+ */
+export declare function loadBaselineConfig(path: string): BaselineConfig;