@simplysf/simply-gitlab-core 0.1.0 → 0.3.0

package/lib/baseline-export.js

@@ -0,0 +1,245 @@
+/*
+ * 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 live project and writes down what it looks like, as a config someone can edit.
+ *
+ * Writing a baseline by hand against forty attributes is miserable and the first draft would be
+ * wrong. Exporting the project that already looks right and deleting what you do not care about is
+ * how anyone actually starts, so this errs towards saying too much: deleting a line is easier than
+ * discovering that a key exists.
+ */
+/** The sections `export` can emit, in the order they appear in the file. */
+export const EXPORTABLE_SECTIONS = [
+    'settings',
+    'protectedBranches',
+    'protectedTags',
+    'approvals',
+    'approvalRules',
+    'pushRules',
+    'variables',
+];
+/**
+ * The project attributes worth putting in a baseline.
+ *
+ * A deliberate list rather than everything `GET /projects/:id` returns: that payload carries ids,
+ * timestamps, counts, and URLs, none of which can be set and all of which would look like intent
+ * once they were sitting in a config file.
+ */
+const SETTING_KEYS = [
+    // Merge request behaviour
+    'merge_method',
+    'squash_option',
+    'only_allow_merge_if_pipeline_succeeds',
+    'only_allow_merge_if_all_discussions_are_resolved',
+    'allow_merge_on_skipped_pipeline',
+    'remove_source_branch_after_merge',
+    'merge_trains_enabled',
+    'printing_merge_request_link_enabled',
+    'resolve_outdated_diff_discussions',
+    'merge_requests_template',
+    // CI/CD
+    'ci_config_path',
+    'build_timeout',
+    'auto_cancel_pending_pipelines',
+    'ci_default_git_depth',
+    'ci_forward_deployment_enabled',
+    'ci_separated_caches',
+    'ci_allow_fork_pipelines_to_run_in_parent_project',
+    'keep_latest_artifact',
+    'auto_devops_enabled',
+    'shared_runners_enabled',
+    'group_runners_enabled',
+    // Repository
+    'default_branch',
+    'issues_enabled',
+    'wiki_enabled',
+    'packages_enabled',
+];
+/** Approval settings that can be set back, as opposed to reported. */
+const APPROVAL_KEYS = [
+    'approvals_before_merge',
+    'reset_approvals_on_push',
+    'disable_overriding_approvers_per_merge_request',
+    'merge_requests_author_approval',
+    'merge_requests_disable_committers_approval',
+    'require_password_to_approve',
+];
+/** Push-rule attributes, minus the id and the project it belongs to. */
+const PUSH_RULE_KEYS = [
+    'commit_message_regex',
+    'commit_message_negative_regex',
+    'branch_name_regex',
+    'author_email_regex',
+    'file_name_regex',
+    'deny_delete_tag',
+    'member_check',
+    'prevent_secrets',
+    'max_file_size',
+    'commit_committer_check',
+    'commit_committer_name_check',
+    'reject_unsigned_commits',
+    'reject_non_dco_commits',
+];
+/** Protected-branch attributes, keeping the access arrays but dropping their server-side ids. */
+const BRANCH_KEYS = ['name', 'allow_force_push', 'code_owner_approval_required'];
+const ACCESS_ARRAYS = ['push_access_levels', 'merge_access_levels', 'unprotect_access_levels'];
+const ACCESS_TARGET = {
+    push_access_levels: 'allowed_to_push',
+    merge_access_levels: 'allowed_to_merge',
+    unprotect_access_levels: 'allowed_to_unprotect',
+};
+function asRecord(value) {
+    return (typeof value === 'object' && value !== null ? value : {});
+}
+/** Copies the named keys that are actually present, so an absent attribute stays absent. */
+function pick(source, keys) {
+    const picked = {};
+    for (const key of keys) {
+        if (source[key] !== undefined && source[key] !== null)
+            picked[key] = source[key];
+    }
+    return picked;
+}
+/**
+ * Turns an access-level array as GitLab reports it into the shape it accepts back.
+ *
+ * The read shape carries `id` and `access_level_description`, neither of which is writable, and the
+ * write shape is a different key. Exporting the raw read would produce a config that fails on its
+ * first apply.
+ */
+function accessEntries(levels) {
+    if (!Array.isArray(levels))
+        return undefined;
+    const mapped = levels.map((raw) => {
+        const level = asRecord(raw);
+        const entry = {};
+        if (typeof level.user_id === 'number')
+            entry.user_id = level.user_id;
+        else if (typeof level.group_id === 'number')
+            entry.group_id = level.group_id;
+        else if (typeof level.access_level === 'number')
+            entry.access_level = level.access_level;
+        return entry;
+    });
+    return mapped.length === 0 ? undefined : mapped;
+}
+function exportBranch(raw) {
+    const branch = asRecord(raw);
+    const entry = pick(branch, BRANCH_KEYS);
+    for (const key of ACCESS_ARRAYS) {
+        const mapped = accessEntries(branch[key]);
+        if (mapped !== undefined)
+            entry[ACCESS_TARGET[key]] = mapped;
+    }
+    return entry;
+}
+function exportTag(raw) {
+    const tag = asRecord(raw);
+    const entry = { name: tag.name };
+    const levels = Array.isArray(tag.create_access_levels) ? tag.create_access_levels.map(asRecord) : [];
+    const first = levels[0];
+    if (first !== undefined && typeof first.access_level === 'number')
+        entry.create_access_level = first.access_level;
+    return entry;
+}
+function exportRule(raw) {
+    const rule = asRecord(raw);
+    // The implicit fallback rule is not something a config declares; exporting it would invite
+    // someone to prune it and lose the project's default approval behaviour.
+    if (rule.rule_type === 'any_approver')
+        return undefined;
+    const entry = { name: rule.name, approvals_required: rule.approvals_required };
+    const usernames = (Array.isArray(rule.eligible_approvers) ? rule.eligible_approvers : [])
+        .map((user) => asRecord(user).username)
+        .filter((username) => typeof username === 'string');
+    if (usernames.length > 0)
+        entry.usernames = usernames.sort();
+    const groups = (Array.isArray(rule.groups) ? rule.groups : [])
+        .map((group) => asRecord(group).full_path)
+        .filter((path) => typeof path === 'string');
+    if (groups.length > 0)
+        entry.groups = groups.sort();
+    const branches = (Array.isArray(rule.protected_branches) ? rule.protected_branches : [])
+        .map((branch) => asRecord(branch).name)
+        .filter((name) => typeof name === 'string');
+    if (branches.length > 0)
+        entry.protectedBranches = branches.sort();
+    else if (rule.applies_to_all_protected_branches === true)
+        entry.applies_to_all_protected_branches = true;
+    return entry;
+}
+/** Variables are exported as metadata. The `value` GitLab returns is never copied into the file. */
+function exportVariable(raw) {
+    const variable = asRecord(raw);
+    return pick(variable, ['key', 'environment_scope', 'variable_type', 'protected', 'masked', 'raw']);
+}
+/** Reads a section, treating a Premium-only endpoint that refuses as simply absent. */
+async function optional(read) {
+    try {
+        return await read();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Reads one project and returns the `project` block of a config describing it. */
+export async function exportProject(client, project, options = {}) {
+    const wanted = new Set(options.sections ?? EXPORTABLE_SECTIONS);
+    const desired = {};
+    if (wanted.has('settings')) {
+        desired.settings = pick(asRecord(await client.getProject(project)), SETTING_KEYS);
+    }
+    if (wanted.has('protectedBranches')) {
+        desired.protectedBranches = (await client.listProtectedBranches(project)).items.map(exportBranch);
+    }
+    if (wanted.has('protectedTags')) {
+        desired.protectedTags = (await client.listProtectedTags(project)).items.map(exportTag);
+    }
+    if (wanted.has('approvals')) {
+        const approvals = await optional(() => client.getApprovalSettings(project));
+        if (approvals !== undefined)
+            desired.approvals = pick(asRecord(approvals), APPROVAL_KEYS);
+    }
+    if (wanted.has('approvalRules')) {
+        const rules = await optional(() => client.listApprovalRules(project));
+        if (rules !== undefined) {
+            desired.approvalRules = rules.items.map(exportRule).filter((rule) => rule !== undefined);
+        }
+    }
+    if (wanted.has('pushRules')) {
+        const pushRules = await optional(() => client.getPushRules(project));
+        if (pushRules !== undefined && pushRules !== null)
+            desired.pushRules = pick(asRecord(pushRules), PUSH_RULE_KEYS);
+    }
+    if (wanted.has('variables')) {
+        const variables = await optional(() => client.listVariables(project, 200));
+        if (variables !== undefined)
+            desired.variables = variables.items.map(exportVariable);
+    }
+    return desired;
+}
+/** A whole config file describing one project, ready to be widened to a group of them. */
+export async function exportConfig(client, project, options = {}) {
+    const desired = await exportProject(client, project, options);
+    return {
+        version: 1,
+        // Deliberately the project it came from, not a group: whoever runs this next should choose the
+        // blast radius on purpose rather than inherit one from an export.
+        targets: { projects: [project] },
+        project: desired,
+    };
+}
+//# sourceMappingURL=baseline-export.js.map

package/lib/baseline-export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline-export.js","sourceRoot":"","sources":["../src/baseline-export.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH;;;;;;;GAOG;AAEH,4EAA4E;AAC5E,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,UAAU;IACV,mBAAmB;IACnB,eAAe;IACf,WAAW;IACX,eAAe;IACf,WAAW;IACX,WAAW;CACH,CAAC;AASX;;;;;;GAMG;AACH,MAAM,YAAY,GAAG;IACnB,0BAA0B;IAC1B,cAAc;IACd,eAAe;IACf,uCAAuC;IACvC,kDAAkD;IAClD,iCAAiC;IACjC,kCAAkC;IAClC,sBAAsB;IACtB,qCAAqC;IACrC,mCAAmC;IACnC,yBAAyB;IACzB,QAAQ;IACR,gBAAgB;IAChB,eAAe;IACf,+BAA+B;IAC/B,sBAAsB;IACtB,+BAA+B;IAC/B,qBAAqB;IACrB,kDAAkD;IAClD,sBAAsB;IACtB,qBAAqB;IACrB,wBAAwB;IACxB,uBAAuB;IACvB,aAAa;IACb,gBAAgB;IAChB,gBAAgB;IAChB,cAAc;IACd,kBAAkB;CACV,CAAC;AAEX,sEAAsE;AACtE,MAAM,aAAa,GAAG;IACpB,wBAAwB;IACxB,yBAAyB;IACzB,gDAAgD;IAChD,gCAAgC;IAChC,4CAA4C;IAC5C,6BAA6B;CACrB,CAAC;AAEX,wEAAwE;AACxE,MAAM,cAAc,GAAG;IACrB,sBAAsB;IACtB,+BAA+B;IAC/B,mBAAmB;IACnB,oBAAoB;IACpB,iBAAiB;IACjB,iBAAiB;IACjB,cAAc;IACd,iBAAiB;IACjB,eAAe;IACf,wBAAwB;IACxB,6BAA6B;IAC7B,yBAAyB;IACzB,wBAAwB;CAChB,CAAC;AAEX,iGAAiG;AACjG,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,kBAAkB,EAAE,8BAA8B,CAAU,CAAC;AAC1F,MAAM,aAAa,GAAG,CAAC,oBAAoB,EAAE,qBAAqB,EAAE,yBAAyB,CAAU,CAAC;AACxG,MAAM,aAAa,GAAqC;IACtD,kBAAkB,EAAE,iBAAiB;IACrC,mBAAmB,EAAE,kBAAkB;IACvC,uBAAuB,EAAE,sBAAsB;CAChD,CAAC;AAEF,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAA4B,CAAC;AAC/F,CAAC;AAED,4FAA4F;AAC5F,SAAS,IAAI,CAAC,MAA+B,EAAE,IAAuB;IACpE,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,IAAI;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACnF,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,SAAS,aAAa,CAAC,MAAe;IACpC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IAC7C,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QAChC,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC5B,MAAM,KAAK,GAA4B,EAAE,CAAC;QAC1C,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ;YAAE,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;aAChE,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ;YAAE,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;aACxE,IAAI,OAAO,KAAK,CAAC,YAAY,KAAK,QAAQ;YAAE,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;QACzF,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;AAClD,CAAC;AAED,SAAS,YAAY,CAAC,GAAY;IAChC,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACxC,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1C,IAAI,MAAM,KAAK,SAAS;YAAE,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC;IAC/D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,SAAS,CAAC,GAAY;IAC7B,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC1B,MAAM,KAAK,GAA4B,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;IAC1D,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,oBAAoB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACrG,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,YAAY,KAAK,QAAQ;QAAE,KAAK,CAAC,mBAAmB,GAAG,KAAK,CAAC,YAAY,CAAC;IAClH,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,UAAU,CAAC,GAAY;IAC9B,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC3B,2FAA2F;IAC3F,yEAAyE;IACzE,IAAI,IAAI,CAAC,SAAS,KAAK,cAAc;QAAE,OAAO,SAAS,CAAC;IAExD,MAAM,KAAK,GAA4B,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,kBAAkB,EAAE,IAAI,CAAC,kBAAkB,EAAE,CAAC;IACxG,MAAM,SAAS,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAC;SACtF,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC;SACtC,MAAM,CAAC,CAAC,QAAQ,EAAsB,EAAE,CAAC,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC;IAC1E,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;IAE7D,MAAM,MAAM,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;SAC3D,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC;SACzC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC;IAC9D,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAEpD,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAC;SACrF,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC;SACtC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC;IAC9D,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,iBAAiB,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;SAC9D,IAAI,IAAI,CAAC,iCAAiC,KAAK,IAAI;QAAE,KAAK,CAAC,iCAAiC,GAAG,IAAI,CAAC;IAEzG,OAAO,KAAK,CAAC;AACf,CAAC;AAED,oGAAoG;AACpG,SAAS,cAAc,CAAC,GAAY;IAClC,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC/B,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;AACrG,CAAC;AAED,uFAAuF;AACvF,KAAK,UAAU,QAAQ,CAAI,IAAsB;IAC/C,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,EAAE,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,mFAAmF;AACnF,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAoB,EACpB,OAAe,EACf,UAAyB,EAAE;IAE3B,MAAM,MAAM,GAAG,IAAI,GAAG,CAAS,OAAO,CAAC,QAAQ,IAAI,mBAAmB,CAAC,CAAC;IACxE,MAAM,OAAO,GAA4B,EAAE,CAAC;IAE5C,IAAI,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3B,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;IACpF,CAAC;IACD,IAAI,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,EAAE,CAAC;QACpC,OAAO,CAAC,iBAAiB,GAAG,CAAC,MAAM,MAAM,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACpG,CAAC;IACD,IAAI,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,CAAC;QAChC,OAAO,CAAC,aAAa,GAAG,CAAC,MAAM,MAAM,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACzF,CAAC;IACD,IAAI,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;QAC5B,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC,CAAC;QAC5E,IAAI,SAAS,KAAK,SAAS;YAAE,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC,CAAC;IAC5F,CAAC;IACD,IAAI,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC;QACtE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,CAAC,aAAa,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAiB,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;QAC1G,CAAC;IACH,CAAC;IACD,IAAI,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;QAC5B,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;QACrE,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,IAAI;YAAE,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC,CAAC;IACnH,CAAC;IACD,IAAI,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;QAC5B,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;QAC3E,IAAI,SAAS,KAAK,SAAS;YAAE,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACvF,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,0FAA0F;AAC1F,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAoB,EACpB,OAAe,EACf,UAAyB,EAAE;IAE3B,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC9D,OAAO;QACL,OAAO,EAAE,CAAC;QACV,+FAA+F;QAC/F,kEAAkE;QAClE,OAAO,EAAE,EAAE,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE;QAChC,OAAO,EAAE,OAAO;KACjB,CAAC;AACJ,CAAC"}

package/lib/baseline-plan.d.ts

@@ -0,0 +1,96 @@
+import { type GroupDesired, type ProjectDesired } from './baseline-config.js';
+import type { GitLabClient } from './gitlab-client.js';
+/**
+ * What a run would do, computed before anything is sent.
+ *
+ * A plan carries two views of the same decision: `changes`, which is what a person reads, and
+ * `actions`, which is what `apply` executes. They are produced together, by one pass, so apply can
+ * only ever do what plan showed — the alternative, re-deriving the work at apply time, is how a
+ * preview stops being a guarantee.
+ */
+export interface BaselinePlan {
+    readonly targets: readonly TargetPlan[];
+}
+export interface TargetPlan {
+    readonly kind: 'project' | 'group';
+    readonly path: string;
+    readonly id: number;
+    readonly sections: readonly SectionPlan[];
+    /** Set when the whole target could not be planned; its sections are then empty. */
+    readonly error?: string;
+}
+export interface SectionPlan {
+    readonly section: string;
+    /** False when the instance does not offer this section — a Premium feature on a Free plan. */
+    readonly supported: boolean;
+    /** Why it is unsupported, for the plan output. */
+    readonly unsupportedReason?: string;
+    readonly changes: readonly Change[];
+    readonly actions: readonly Action[];
+}
+export type ChangeOp = 'create' | 'update' | 'delete' | 'recreate' | 'report';
+export interface Change {
+    readonly op: ChangeOp;
+    /** What changed: an attribute name for `update`, an entry's identity otherwise. */
+    readonly key: string;
+    readonly from?: unknown;
+    readonly to?: unknown;
+    /** Extra context a reader needs — why a recreate, or why a delete is not being executed. */
+    readonly detail?: string;
+}
+/** One request `apply` will make. Opaque to the renderer; executed by `baseline-apply.ts`. */
+export type Action = {
+    readonly kind: 'updateProject';
+    readonly body: Record<string, unknown>;
+} | {
+    readonly kind: 'updateGroup';
+    readonly body: Record<string, unknown>;
+} | {
+    readonly kind: 'protectBranch';
+    readonly body: Record<string, unknown>;
+} | {
+    readonly kind: 'patchProtectedBranch';
+    readonly name: string;
+    readonly body: Record<string, unknown>;
+} | {
+    readonly kind: 'unprotectBranch';
+    readonly name: string;
+} | {
+    readonly kind: 'protectTag';
+    readonly body: Record<string, unknown>;
+} | {
+    readonly kind: 'unprotectTag';
+    readonly name: string;
+} | {
+    readonly kind: 'updateApprovalSettings';
+    readonly body: Record<string, unknown>;
+} | {
+    readonly kind: 'createApprovalRule';
+    readonly body: Record<string, unknown>;
+    readonly branches?: readonly string[];
+} | {
+    readonly kind: 'updateApprovalRule';
+    readonly ruleId: number;
+    readonly body: Record<string, unknown>;
+    readonly branches?: readonly string[];
+} | {
+    readonly kind: 'deleteApprovalRule';
+    readonly ruleId: number;
+} | {
+    readonly kind: 'setPushRules';
+    readonly body: Record<string, unknown>;
+    readonly exists: boolean;
+};
+/** Whether a plan would change anything if applied. */
+export declare function hasChanges(plan: BaselinePlan): boolean;
+/** Every drift a plan found, including the parts it would not correct. */
+export declare function hasDrift(plan: BaselinePlan): boolean;
+/** Plans one project. Never throws for an instance failure; the target carries the error instead. */
+export declare function planProject(client: GitLabClient, target: {
+    readonly path: string;
+    readonly id: number;
+}, desired: ProjectDesired): Promise<TargetPlan>;
+export declare function planGroup(client: GitLabClient, target: {
+    readonly path: string;
+    readonly id: number;
+}, desired: GroupDesired): Promise<TargetPlan>;