@simplysf/simply-gitlab 0.2.0 → 0.4.0

package/lib/commands/gitlab/config/plan.js

@@ -0,0 +1,69 @@
+/*
+ * 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 { Flags } from '@oclif/core';
+import { CliError, hasDrift, loadBaselineConfig, planRun, planToJson, renderPlan } from '@simplysf/simply-gitlab-core';
+import { GitLabCommand } from '../../../shared/base-command.js';
+import { baselineFlags } from '../../../shared/baseline-flags.js';
+export default class GitlabConfigPlan extends GitLabCommand {
+    static summary = 'Report how projects differ from a baseline config.';
+    static description = 'Reads the baseline, expands its targets, and prints what differs on each one. Nothing is ' +
+        'sent that changes anything, so this is safe to run against every project you have.\n\n' +
+        'Only the attributes the config declares are compared. A project with forty settings the ' +
+        'config never mentions shows nothing for them — that is what makes a baseline safe to point ' +
+        'at projects that already exist.\n\n' +
+        'Entries that exist on the instance but are not in the config are shown as removals, marked ' +
+        'as not pruned unless that section opts into pruning. Seeing what you are choosing not to fix ' +
+        'is most of the value of running this across fifty projects.\n\n' +
+        'Use --fail-on-drift in a scheduled job: it exits 1 when anything differs, so CI can tell you ' +
+        'that something drifted without anyone having to read the output.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --config ./baseline.json',
+        '<%= config.bin %> <%= command.id %> --config ./baseline.json --target group/project',
+        '<%= config.bin %> <%= command.id %> --config ./baseline.json --fail-on-drift',
+        '<%= config.bin %> <%= command.id %> --config ./baseline.json --json | jq .summary',
+    ];
+    static flags = {
+        ...baselineFlags,
+        'fail-on-drift': Flags.boolean({
+            summary: 'Exit 1 when any target differs from the baseline.',
+            default: false,
+        }),
+    };
+    async run() {
+        const config = loadBaselineConfig(this.flags.config);
+        const { targets, plan } = await planRun(this.gitlab(), config, {
+            concurrency: this.flags.concurrency,
+            failFast: this.flags['fail-fast'],
+            only: this.flags.target,
+        });
+        if (!this.jsonEnabled()) {
+            // What a run is about to touch is the first question anyone should ask and the last one
+            // they should have to guess at.
+            this.log(`Targets: ${targets.projects.length} project(s), ${targets.groups.length} group(s).`);
+            if (targets.excluded.length > 0)
+                this.logSafe(`Excluded: ${targets.excluded.join(', ')}`);
+            this.log('');
+            this.logSafe(renderPlan(plan));
+        }
+        const drifted = hasDrift(plan);
+        if (this.flags['fail-on-drift'] && drifted) {
+            // Deliberately after the output: the point of the flag is to fail a job, not to hide why.
+            throw new CliError('The baseline does not match. Run without --fail-on-drift to see the plan.');
+        }
+        return planToJson(plan);
+    }
+}
+//# sourceMappingURL=plan.js.map

package/lib/commands/gitlab/config/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../../../src/commands/gitlab/config/plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,kBAAkB,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AACvH,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAElE,MAAM,CAAC,OAAO,OAAO,gBAAiB,SAAQ,aAAsC;IAC3E,MAAM,CAAmB,OAAO,GAAG,oDAAoD,CAAC;IACxF,MAAM,CAAmB,WAAW,GACzC,2FAA2F;QAC3F,wFAAwF;QACxF,0FAA0F;QAC1F,6FAA6F;QAC7F,qCAAqC;QACrC,6FAA6F;QAC7F,+FAA+F;QAC/F,iEAAiE;QACjE,+FAA+F;QAC/F,kEAAkE,CAAC;IAE9D,MAAM,CAAmB,QAAQ,GAAG;QACzC,8DAA8D;QAC9D,qFAAqF;QACrF,8EAA8E;QAC9E,mFAAmF;KACpF,CAAC;IAEK,MAAM,CAAmB,KAAK,GAAG;QACtC,GAAG,aAAa;QAChB,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC;YAC7B,OAAO,EAAE,mDAAmD;YAC5D,OAAO,EAAE,KAAK;SACf,CAAC;KACH,CAAC;IAEK,KAAK,CAAC,GAAG;QACd,MAAM,MAAM,GAAG,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACrD,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE;YAC7D,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW;YACnC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC;YACjC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM;SACxB,CAAC,CAAC;QAEH,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,wFAAwF;YACxF,gCAAgC;YAChC,IAAI,CAAC,GAAG,CAAC,YAAY,OAAO,CAAC,QAAQ,CAAC,MAAM,gBAAgB,OAAO,CAAC,MAAM,CAAC,MAAM,YAAY,CAAC,CAAC;YAC/F,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;gBAAE,IAAI,CAAC,OAAO,CAAC,aAAa,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC1F,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACb,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;QACjC,CAAC;QAED,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,IAAI,OAAO,EAAE,CAAC;YAC3C,0FAA0F;YAC1F,MAAM,IAAI,QAAQ,CAAC,2EAA2E,CAAC,CAAC;QAClG,CAAC;QAED,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC"}

package/lib/shared/baseline-flags.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The flags `config plan` and `config apply` share, defined once so the two cannot disagree about
+ * what a run means. Both commands read the same file and resolve the same targets; only what they
+ * do afterwards differs.
+ */
+export declare const baselineFlags: {
+    config: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    target: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    concurrency: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+    'fail-fast': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+};

package/lib/shared/baseline-flags.js

@@ -0,0 +1,50 @@
+/*
+ * 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 { Flags } from '@oclif/core';
+import { DEFAULT_CONCURRENCY } from '@simplysf/simply-gitlab-core';
+/**
+ * The flags `config plan` and `config apply` share, defined once so the two cannot disagree about
+ * what a run means. Both commands read the same file and resolve the same targets; only what they
+ * do afterwards differs.
+ */
+export const baselineFlags = {
+    config: Flags.string({
+        char: 'c',
+        summary: 'Path to the baseline configuration file.',
+        required: true,
+    }),
+    target: Flags.string({
+        summary: 'Limit the run to this project path. Repeatable.',
+        description: 'Narrows a run without editing the config, for the loop of fixing one project and checking ' +
+            'it again. Naming a project the config does not target is an error rather than a silent ' +
+            'no-op.',
+        multiple: true,
+    }),
+    concurrency: Flags.integer({
+        summary: 'How many targets to work on at once.',
+        description: 'Small by default. The client already retries a rate-limited request with a capped ' +
+            'Retry-After, so raising this trades a shared instance responsiveness for very little ' +
+            'wall-clock time.',
+        default: DEFAULT_CONCURRENCY,
+        min: 1,
+        max: 16,
+    }),
+    'fail-fast': Flags.boolean({
+        summary: 'Stop at the first target that fails instead of continuing.',
+        default: false,
+    }),
+};
+//# sourceMappingURL=baseline-flags.js.map

package/lib/shared/baseline-flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline-flags.js","sourceRoot":"","sources":["../../src/shared/baseline-flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAEnE;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC;QACnB,IAAI,EAAE,GAAG;QACT,OAAO,EAAE,0CAA0C;QACnD,QAAQ,EAAE,IAAI;KACf,CAAC;IACF,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC;QACnB,OAAO,EAAE,iDAAiD;QAC1D,WAAW,EACT,4FAA4F;YAC5F,yFAAyF;YACzF,QAAQ;QACV,QAAQ,EAAE,IAAI;KACf,CAAC;IACF,WAAW,EAAE,KAAK,CAAC,OAAO,CAAC;QACzB,OAAO,EAAE,sCAAsC;QAC/C,WAAW,EACT,oFAAoF;YACpF,uFAAuF;YACvF,kBAAkB;QACpB,OAAO,EAAE,mBAAmB;QAC5B,GAAG,EAAE,CAAC;QACN,GAAG,EAAE,EAAE;KACR,CAAC;IACF,WAAW,EAAE,KAAK,CAAC,OAAO,CAAC;QACzB,OAAO,EAAE,4DAA4D;QACrE,OAAO,EAAE,KAAK;KACf,CAAC;CACH,CAAC"}