@simplysf/simply-gitlab 0.4.0 → 0.5.0

package/oclif.manifest.json

@@ -325,13 +325,14 @@
         "list:branch:gitlab"
       ]
     },
-    "gitlab:commit:create": {
+    "gitlab:config:apply": {
       "aliases": [],
       "args": {},
-      "description": "Sends one commit containing a batch of actions — create, update, delete, move, chmod — which is how GitLab writes more than one file atomically. The actions are JSON, supplied with --actions or inside a --body-file, because there is no readable flag form for a list of file operations.\n\nEach action is an object with an \"action\" and a \"file_path\"; create and update also need \"content\", move needs \"previous_path\", and chmod needs \"execute_filemode\". Those rules are checked before anything is sent, so a bad entry names its own index.\n\nUse --dry-run to see exactly what would be sent.",
+      "description": "Computes the same plan as config plan, then executes it. Only what the plan showed is sent, so a preview is a guarantee rather than an approximation, and a second run against a converged project sends no requests at all.\n\nSections are applied in a fixed order — settings, protected branches, protected tags, approval settings, approval rules, push rules — because an approval rule scoped to a branch needs that branch protected before it can reference it.\n\nBy default the config only adds and corrects what it declares. A section that sets \"prune\": true also deletes entries the config does not mention.\n\nOne target failing does not abandon the rest; the summary says which ones failed and where they stopped. There is no transaction across GitLab endpoints, so a target that failed part-way keeps the sections already applied — run config plan afterwards to see what is left.",
       "examples": [
-        "<%= config.bin %> <%= command.id %> --project group/project --branch main --message \"chore: tidy\" --actions '[{\"action\":\"delete\",\"file_path\":\"old.txt\"}]'",
-        "<%= config.bin %> <%= command.id %> --project group/project --branch main --message \"feat: batch\" --body-file ./commit.json --dry-run"
+        "<%= config.bin %> <%= command.id %> --config ./baseline.json --dry-run",
+        "<%= config.bin %> <%= command.id %> --config ./baseline.json",
+        "<%= config.bin %> <%= command.id %> --config ./baseline.json --target group/project"
       ],
       "flags": {
         "json": {
@@ -369,103 +370,53 @@
           "multiple": false,
           "type": "option"
         },
-        "project": {
-          "char": "p",
-          "env": "GITLAB_PROJECT",
-          "name": "project",
+        "config": {
+          "char": "c",
+          "name": "config",
           "required": true,
-          "summary": "Project id, or its full path such as group/subgroup/project.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "dry-run": {
-          "name": "dry-run",
-          "summary": "Print the request that would be sent and exit without sending it.",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "branch": {
-          "name": "branch",
-          "summary": "Branch to commit to.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "message": {
-          "name": "message",
-          "summary": "Commit message.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "actions": {
-          "name": "actions",
-          "summary": "JSON array of file actions.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "start-branch": {
-          "name": "start-branch",
-          "summary": "Branch to create --branch from, if it does not exist.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "start-sha": {
-          "name": "start-sha",
-          "summary": "Commit SHA to start the new commit from.",
+          "summary": "Path to the baseline configuration file.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "author-email": {
-          "name": "author-email",
-          "summary": "Commit author email.",
+        "target": {
+          "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.",
+          "name": "target",
+          "summary": "Limit the run to this project path. Repeatable.",
           "hasDynamicHelp": false,
-          "multiple": false,
+          "multiple": true,
           "type": "option"
         },
-        "author-name": {
-          "name": "author-name",
-          "summary": "Commit author name.",
+        "concurrency": {
+          "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.",
+          "name": "concurrency",
+          "summary": "How many targets to work on at once.",
+          "default": 4,
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "force": {
-          "name": "force",
-          "summary": "Overwrite the branch with the new commit.",
+        "fail-fast": {
+          "name": "fail-fast",
+          "summary": "Stop at the first target that fails instead of continuing.",
           "allowNo": false,
           "type": "boolean"
         },
-        "body": {
-          "exclusive": [
-            "body-file"
-          ],
-          "name": "body",
-          "summary": "Raw JSON request body.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "body-file": {
-          "name": "body-file",
-          "summary": "Path to a file holding the raw JSON request body.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
+        "dry-run": {
+          "name": "dry-run",
+          "summary": "Print the request that would be sent and exit without sending it.",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "gitlab:commit:create",
+      "id": "gitlab:config:apply",
       "pluginAlias": "@simplysf/simply-gitlab",
       "pluginName": "@simplysf/simply-gitlab",
       "pluginType": "core",
       "strict": true,
-      "summary": "Commit several file changes at once.",
+      "summary": "Bring projects onto a baseline config.",
       "enableJsonFlag": true,
       "isWrite": true,
       "isESM": true,
@@ -473,26 +424,26 @@
         "lib",
         "commands",
         "gitlab",
-        "commit",
-        "create.js"
+        "config",
+        "apply.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "gitlab:commit:create",
-        "commit:gitlab:create",
-        "commit:create:gitlab",
-        "gitlab:create:commit",
-        "create:gitlab:commit",
-        "create:commit:gitlab"
+        "gitlab:config:apply",
+        "config:gitlab:apply",
+        "config:apply:gitlab",
+        "gitlab:apply:config",
+        "apply:gitlab:config",
+        "apply:config:gitlab"
       ]
     },
-    "gitlab:commit:diff": {
+    "gitlab:config:export": {
       "aliases": [],
       "args": {},
-      "description": "Prints the unified diff for each file the commit touched. GitLab truncates very large diffs server-side and says so in the payload, so --stat is worth reaching for first on a big commit: it lists the files without any hunks.",
+      "description": "Reads one project and prints a configuration file that describes it, ready to be edited and pointed at the rest of your projects. Writing a baseline by hand against forty attributes is miserable and the first draft is wrong; exporting the project that already looks right and deleting what you do not care about is the way to start.\n\nThe output is deliberately verbose — every supported key, not a curated subset — because deleting a line is easier than discovering that a key exists. Variables are exported as metadata only: keys, scopes, and flags, never values.\n\nThe exported targets name only the project it came from. Widen that on purpose rather than inheriting a blast radius from an export.",
       "examples": [
-        "<%= config.bin %> <%= command.id %> --project group/project --sha 9a1b2c3",
-        "<%= config.bin %> <%= command.id %> --project group/project --sha 9a1b2c3 --stat"
+        "<%= config.bin %> <%= command.id %> --project group/project > baseline.json",
+        "<%= config.bin %> <%= command.id %> --project group/project --section settings,protectedBranches"
       ],
       "flags": {
         "json": {
@@ -540,29 +491,32 @@
           "multiple": false,
           "type": "option"
         },
-        "sha": {
-          "name": "sha",
-          "required": true,
-          "summary": "Commit SHA, or the name of a branch or tag.",
+        "section": {
+          "name": "section",
+          "summary": "Comma-separated sections to export. Defaults to all of them.",
+          "delimiter": ",",
           "hasDynamicHelp": false,
-          "multiple": false,
+          "multiple": true,
+          "options": [
+            "settings",
+            "protectedBranches",
+            "protectedTags",
+            "approvals",
+            "approvalRules",
+            "pushRules",
+            "variables"
+          ],
           "type": "option"
-        },
-        "stat": {
-          "name": "stat",
-          "summary": "List the changed files without printing the hunks.",
-          "allowNo": false,
-          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "gitlab:commit:diff",
+      "id": "gitlab:config:export",
       "pluginAlias": "@simplysf/simply-gitlab",
       "pluginName": "@simplysf/simply-gitlab",
       "pluginType": "core",
       "strict": true,
-      "summary": "Show the changes a commit made.",
+      "summary": "Write a baseline config describing an existing project.",
       "enableJsonFlag": true,
       "isWrite": false,
       "isESM": true,
@@ -570,27 +524,28 @@
         "lib",
         "commands",
         "gitlab",
-        "commit",
-        "diff.js"
+        "config",
+        "export.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "gitlab:commit:diff",
-        "commit:gitlab:diff",
-        "commit:diff:gitlab",
-        "gitlab:diff:commit",
-        "diff:gitlab:commit",
-        "diff:commit:gitlab"
+        "gitlab:config:export",
+        "config:gitlab:export",
+        "config:export:gitlab",
+        "gitlab:export:config",
+        "export:gitlab:config",
+        "export:config:gitlab"
       ]
     },
-    "gitlab:commit:list": {
+    "gitlab:config:plan": {
       "aliases": [],
       "args": {},
-      "description": "Walks the history of a ref, newest first. --path narrows to commits that touched one file or directory, which is the fastest way to answer \"when did this change and who changed it\".\n\n--since and --until take ISO 8601 timestamps (2026-01-31T00:00:00Z); a bare date works too.",
+      "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\nOnly 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\nEntries 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\nUse --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.",
       "examples": [
-        "<%= config.bin %> <%= command.id %> --project group/project --ref main --limit 10",
-        "<%= config.bin %> <%= command.id %> --project group/project --path src/index.ts",
-        "<%= config.bin %> <%= command.id %> --project group/project --since 2026-01-01 --until 2026-02-01"
+        "<%= 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"
       ],
       "flags": {
         "json": {
@@ -628,74 +583,53 @@
           "multiple": false,
           "type": "option"
         },
-        "project": {
-          "char": "p",
-          "env": "GITLAB_PROJECT",
-          "name": "project",
+        "config": {
+          "char": "c",
+          "name": "config",
           "required": true,
-          "summary": "Project id, or its full path such as group/subgroup/project.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "limit": {
-          "name": "limit",
-          "summary": "Maximum number of commits to return across all pages.",
-          "default": 20,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "ref": {
-          "name": "ref",
-          "summary": "Branch, tag, or SHA to list from. Defaults to the default branch.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "path": {
-          "name": "path",
-          "summary": "Only commits that touched this file or directory.",
+          "summary": "Path to the baseline configuration file.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "since": {
-          "name": "since",
-          "summary": "Only commits on or after this ISO 8601 timestamp.",
+        "target": {
+          "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.",
+          "name": "target",
+          "summary": "Limit the run to this project path. Repeatable.",
           "hasDynamicHelp": false,
-          "multiple": false,
+          "multiple": true,
           "type": "option"
         },
-        "until": {
-          "name": "until",
-          "summary": "Only commits on or before this ISO 8601 timestamp.",
+        "concurrency": {
+          "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.",
+          "name": "concurrency",
+          "summary": "How many targets to work on at once.",
+          "default": 4,
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "author": {
-          "name": "author",
-          "summary": "Only commits by this author name or email.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
+        "fail-fast": {
+          "name": "fail-fast",
+          "summary": "Stop at the first target that fails instead of continuing.",
+          "allowNo": false,
+          "type": "boolean"
         },
-        "stats": {
-          "name": "stats",
-          "summary": "Include per-commit line counts in the JSON payload.",
+        "fail-on-drift": {
+          "name": "fail-on-drift",
+          "summary": "Exit 1 when any target differs from the baseline.",
           "allowNo": false,
           "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "gitlab:commit:list",
+      "id": "gitlab:config:plan",
       "pluginAlias": "@simplysf/simply-gitlab",
       "pluginName": "@simplysf/simply-gitlab",
       "pluginType": "core",
       "strict": true,
-      "summary": "List repository commits.",
+      "summary": "Report how projects differ from a baseline config.",
       "enableJsonFlag": true,
       "isWrite": false,
       "isESM": true,
@@ -703,26 +637,26 @@
         "lib",
         "commands",
         "gitlab",
-        "commit",
-        "list.js"
+        "config",
+        "plan.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "gitlab:commit:list",
-        "commit:gitlab:list",
-        "commit:list:gitlab",
-        "gitlab:list:commit",
-        "list:gitlab:commit",
-        "list:commit:gitlab"
+        "gitlab:config:plan",
+        "config:gitlab:plan",
+        "config:plan:gitlab",
+        "gitlab:plan:config",
+        "plan:gitlab:config",
+        "plan:config:gitlab"
       ]
     },
-    "gitlab:commit:view": {
+    "gitlab:commit:create": {
       "aliases": [],
       "args": {},
-      "description": "Accepts a full or short SHA, or the name of a branch or tag — in which case the commit at its tip is shown, so the answer changes as the branch moves. Use commit diff for the changes themselves.",
+      "description": "Sends one commit containing a batch of actions — create, update, delete, move, chmod — which is how GitLab writes more than one file atomically. The actions are JSON, supplied with --actions or inside a --body-file, because there is no readable flag form for a list of file operations.\n\nEach action is an object with an \"action\" and a \"file_path\"; create and update also need \"content\", move needs \"previous_path\", and chmod needs \"execute_filemode\". Those rules are checked before anything is sent, so a bad entry names its own index.\n\nUse --dry-run to see exactly what would be sent.",
       "examples": [
-        "<%= config.bin %> <%= command.id %> --project group/project --sha 9a1b2c3",
-        "<%= config.bin %> <%= command.id %> --project group/project --sha main --json"
+        "<%= config.bin %> <%= command.id %> --project group/project --branch main --message \"chore: tidy\" --actions '[{\"action\":\"delete\",\"file_path\":\"old.txt\"}]'",
+        "<%= config.bin %> <%= command.id %> --project group/project --branch main --message \"feat: batch\" --body-file ./commit.json --dry-run"
       ],
       "flags": {
         "json": {
@@ -770,10 +704,80 @@
           "multiple": false,
           "type": "option"
         },
-        "sha": {
-          "name": "sha",
-          "required": true,
-          "summary": "Commit SHA, or the name of a branch or tag.",
+        "dry-run": {
+          "name": "dry-run",
+          "summary": "Print the request that would be sent and exit without sending it.",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "branch": {
+          "name": "branch",
+          "summary": "Branch to commit to.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "message": {
+          "name": "message",
+          "summary": "Commit message.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "actions": {
+          "name": "actions",
+          "summary": "JSON array of file actions.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "start-branch": {
+          "name": "start-branch",
+          "summary": "Branch to create --branch from, if it does not exist.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "start-sha": {
+          "name": "start-sha",
+          "summary": "Commit SHA to start the new commit from.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "author-email": {
+          "name": "author-email",
+          "summary": "Commit author email.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "author-name": {
+          "name": "author-name",
+          "summary": "Commit author name.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "force": {
+          "name": "force",
+          "summary": "Overwrite the branch with the new commit.",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "body": {
+          "exclusive": [
+            "body-file"
+          ],
+          "name": "body",
+          "summary": "Raw JSON request body.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "body-file": {
+          "name": "body-file",
+          "summary": "Path to a file holding the raw JSON request body.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -781,40 +785,39 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "gitlab:commit:view",
+      "id": "gitlab:commit:create",
       "pluginAlias": "@simplysf/simply-gitlab",
       "pluginName": "@simplysf/simply-gitlab",
       "pluginType": "core",
       "strict": true,
-      "summary": "Show one commit.",
+      "summary": "Commit several file changes at once.",
       "enableJsonFlag": true,
-      "isWrite": false,
+      "isWrite": true,
       "isESM": true,
       "relativePath": [
         "lib",
         "commands",
         "gitlab",
         "commit",
-        "view.js"
+        "create.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "gitlab:commit:view",
-        "commit:gitlab:view",
-        "commit:view:gitlab",
-        "gitlab:view:commit",
-        "view:gitlab:commit",
-        "view:commit:gitlab"
+        "gitlab:commit:create",
+        "commit:gitlab:create",
+        "commit:create:gitlab",
+        "gitlab:create:commit",
+        "create:gitlab:commit",
+        "create:commit:gitlab"
       ]
     },
-    "gitlab:config:apply": {
+    "gitlab:commit:diff": {
       "aliases": [],
       "args": {},
-      "description": "Computes the same plan as config plan, then executes it. Only what the plan showed is sent, so a preview is a guarantee rather than an approximation, and a second run against a converged project sends no requests at all.\n\nSections are applied in a fixed order — settings, protected branches, protected tags, approval settings, approval rules, push rules — because an approval rule scoped to a branch needs that branch protected before it can reference it.\n\nBy default the config only adds and corrects what it declares. A section that sets \"prune\": true also deletes entries the config does not mention.\n\nOne target failing does not abandon the rest; the summary says which ones failed and where they stopped. There is no transaction across GitLab endpoints, so a target that failed part-way keeps the sections already applied — run config plan afterwards to see what is left.",
+      "description": "Prints the unified diff for each file the commit touched. GitLab truncates very large diffs server-side and says so in the payload, so --stat is worth reaching for first on a big commit: it lists the files without any hunks.",
       "examples": [
-        "<%= config.bin %> <%= command.id %> --config ./baseline.json --dry-run",
-        "<%= config.bin %> <%= command.id %> --config ./baseline.json",
-        "<%= config.bin %> <%= command.id %> --config ./baseline.json --target group/project"
+        "<%= config.bin %> <%= command.id %> --project group/project --sha 9a1b2c3",
+        "<%= config.bin %> <%= command.id %> --project group/project --sha 9a1b2c3 --stat"
       ],
       "flags": {
         "json": {
@@ -852,80 +855,67 @@
           "multiple": false,
           "type": "option"
         },
-        "config": {
-          "char": "c",
-          "name": "config",
+        "project": {
+          "char": "p",
+          "env": "GITLAB_PROJECT",
+          "name": "project",
           "required": true,
-          "summary": "Path to the baseline configuration file.",
+          "summary": "Project id, or its full path such as group/subgroup/project.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "target": {
-          "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.",
-          "name": "target",
-          "summary": "Limit the run to this project path. Repeatable.",
-          "hasDynamicHelp": false,
-          "multiple": true,
-          "type": "option"
-        },
-        "concurrency": {
-          "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.",
-          "name": "concurrency",
-          "summary": "How many targets to work on at once.",
-          "default": 4,
+        "sha": {
+          "name": "sha",
+          "required": true,
+          "summary": "Commit SHA, or the name of a branch or tag.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "fail-fast": {
-          "name": "fail-fast",
-          "summary": "Stop at the first target that fails instead of continuing.",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "dry-run": {
-          "name": "dry-run",
-          "summary": "Print the request that would be sent and exit without sending it.",
+        "stat": {
+          "name": "stat",
+          "summary": "List the changed files without printing the hunks.",
           "allowNo": false,
           "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "gitlab:config:apply",
+      "id": "gitlab:commit:diff",
       "pluginAlias": "@simplysf/simply-gitlab",
       "pluginName": "@simplysf/simply-gitlab",
       "pluginType": "core",
       "strict": true,
-      "summary": "Bring projects onto a baseline config.",
+      "summary": "Show the changes a commit made.",
       "enableJsonFlag": true,
-      "isWrite": true,
+      "isWrite": false,
       "isESM": true,
       "relativePath": [
         "lib",
         "commands",
         "gitlab",
-        "config",
-        "apply.js"
+        "commit",
+        "diff.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "gitlab:config:apply",
-        "config:gitlab:apply",
-        "config:apply:gitlab",
-        "gitlab:apply:config",
-        "apply:gitlab:config",
-        "apply:config:gitlab"
+        "gitlab:commit:diff",
+        "commit:gitlab:diff",
+        "commit:diff:gitlab",
+        "gitlab:diff:commit",
+        "diff:gitlab:commit",
+        "diff:commit:gitlab"
       ]
     },
-    "gitlab:config:export": {
+    "gitlab:commit:list": {
       "aliases": [],
       "args": {},
-      "description": "Reads one project and prints a configuration file that describes it, ready to be edited and pointed at the rest of your projects. Writing a baseline by hand against forty attributes is miserable and the first draft is wrong; exporting the project that already looks right and deleting what you do not care about is the way to start.\n\nThe output is deliberately verbose — every supported key, not a curated subset — because deleting a line is easier than discovering that a key exists. Variables are exported as metadata only: keys, scopes, and flags, never values.\n\nThe exported targets name only the project it came from. Widen that on purpose rather than inheriting a blast radius from an export.",
+      "description": "Walks the history of a ref, newest first. --path narrows to commits that touched one file or directory, which is the fastest way to answer \"when did this change and who changed it\".\n\n--since and --until take ISO 8601 timestamps (2026-01-31T00:00:00Z); a bare date works too.",
       "examples": [
-        "<%= config.bin %> <%= command.id %> --project group/project > baseline.json",
-        "<%= config.bin %> <%= command.id %> --project group/project --section settings,protectedBranches"
+        "<%= config.bin %> <%= command.id %> --project group/project --ref main --limit 10",
+        "<%= config.bin %> <%= command.id %> --project group/project --path src/index.ts",
+        "<%= config.bin %> <%= command.id %> --project group/project --since 2026-01-01 --until 2026-02-01"
       ],
       "flags": {
         "json": {
@@ -973,32 +963,64 @@
           "multiple": false,
           "type": "option"
         },
-        "section": {
-          "name": "section",
-          "summary": "Comma-separated sections to export. Defaults to all of them.",
-          "delimiter": ",",
+        "limit": {
+          "name": "limit",
+          "summary": "Maximum number of commits to return across all pages.",
+          "default": 20,
           "hasDynamicHelp": false,
-          "multiple": true,
-          "options": [
-            "settings",
-            "protectedBranches",
-            "protectedTags",
-            "approvals",
-            "approvalRules",
-            "pushRules",
-            "variables"
-          ],
+          "multiple": false,
+          "type": "option"
+        },
+        "ref": {
+          "name": "ref",
+          "summary": "Branch, tag, or SHA to list from. Defaults to the default branch.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "path": {
+          "name": "path",
+          "summary": "Only commits that touched this file or directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "since": {
+          "name": "since",
+          "summary": "Only commits on or after this ISO 8601 timestamp.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "until": {
+          "name": "until",
+          "summary": "Only commits on or before this ISO 8601 timestamp.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "author": {
+          "name": "author",
+          "summary": "Only commits by this author name or email.",
+          "hasDynamicHelp": false,
+          "multiple": false,
           "type": "option"
+        },
+        "stats": {
+          "name": "stats",
+          "summary": "Include per-commit line counts in the JSON payload.",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "gitlab:config:export",
+      "id": "gitlab:commit:list",
       "pluginAlias": "@simplysf/simply-gitlab",
       "pluginName": "@simplysf/simply-gitlab",
       "pluginType": "core",
       "strict": true,
-      "summary": "Write a baseline config describing an existing project.",
+      "summary": "List repository commits.",
       "enableJsonFlag": true,
       "isWrite": false,
       "isESM": true,
@@ -1006,28 +1028,26 @@
         "lib",
         "commands",
         "gitlab",
-        "config",
-        "export.js"
+        "commit",
+        "list.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "gitlab:config:export",
-        "config:gitlab:export",
-        "config:export:gitlab",
-        "gitlab:export:config",
-        "export:gitlab:config",
-        "export:config:gitlab"
+        "gitlab:commit:list",
+        "commit:gitlab:list",
+        "commit:list:gitlab",
+        "gitlab:list:commit",
+        "list:gitlab:commit",
+        "list:commit:gitlab"
       ]
     },
-    "gitlab:config:plan": {
+    "gitlab:commit:view": {
       "aliases": [],
       "args": {},
-      "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\nOnly 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\nEntries 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\nUse --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.",
+      "description": "Accepts a full or short SHA, or the name of a branch or tag — in which case the commit at its tip is shown, so the answer changes as the branch moves. Use commit diff for the changes themselves.",
       "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"
+        "<%= config.bin %> <%= command.id %> --project group/project --sha 9a1b2c3",
+        "<%= config.bin %> <%= command.id %> --project group/project --sha main --json"
       ],
       "flags": {
         "json": {
@@ -1065,53 +1085,33 @@
           "multiple": false,
           "type": "option"
         },
-        "config": {
-          "char": "c",
-          "name": "config",
+        "project": {
+          "char": "p",
+          "env": "GITLAB_PROJECT",
+          "name": "project",
           "required": true,
-          "summary": "Path to the baseline configuration file.",
+          "summary": "Project id, or its full path such as group/subgroup/project.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "target": {
-          "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.",
-          "name": "target",
-          "summary": "Limit the run to this project path. Repeatable.",
-          "hasDynamicHelp": false,
-          "multiple": true,
-          "type": "option"
-        },
-        "concurrency": {
-          "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.",
-          "name": "concurrency",
-          "summary": "How many targets to work on at once.",
-          "default": 4,
+        "sha": {
+          "name": "sha",
+          "required": true,
+          "summary": "Commit SHA, or the name of a branch or tag.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
-        },
-        "fail-fast": {
-          "name": "fail-fast",
-          "summary": "Stop at the first target that fails instead of continuing.",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "fail-on-drift": {
-          "name": "fail-on-drift",
-          "summary": "Exit 1 when any target differs from the baseline.",
-          "allowNo": false,
-          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "gitlab:config:plan",
+      "id": "gitlab:commit:view",
       "pluginAlias": "@simplysf/simply-gitlab",
       "pluginName": "@simplysf/simply-gitlab",
       "pluginType": "core",
       "strict": true,
-      "summary": "Report how projects differ from a baseline config.",
+      "summary": "Show one commit.",
       "enableJsonFlag": true,
       "isWrite": false,
       "isESM": true,
@@ -1119,17 +1119,17 @@
         "lib",
         "commands",
         "gitlab",
-        "config",
-        "plan.js"
+        "commit",
+        "view.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "gitlab:config:plan",
-        "config:gitlab:plan",
-        "config:plan:gitlab",
-        "gitlab:plan:config",
-        "plan:gitlab:config",
-        "plan:config:gitlab"
+        "gitlab:commit:view",
+        "commit:gitlab:view",
+        "commit:view:gitlab",
+        "gitlab:view:commit",
+        "view:gitlab:commit",
+        "view:commit:gitlab"
       ]
     },
     "gitlab:file:create": {
@@ -3054,5 +3054,5 @@
       ]
     }
   },
-  "version": "0.4.0"
+  "version": "0.5.0"
 }