@simplysf/simply-gitlab 0.4.0 → 0.5.0

package/README.md

@@ -13,6 +13,12 @@ human-readable by default and raw JSON with `--json`, and every command that cha
 The same capabilities are available to AI agents through
 [`@simplysf/simply-gitlab-mcp`](https://github.com/SimplySF/simply-gitlab/tree/main/packages/simply-gitlab-mcp).
 
+## Documentation
+
+Guides and the full command reference: **https://simplysf.github.io/simply-cli/gitlab/**
+
+The guides also ship inside this package, under [`docs/`](docs).
+
 ## Install
 
 `@simplysf/simply-gitlab` is a plugin of the `simply` CLI, not a command of its own. Install the host; this

package/docs/getting-started.md

@@ -0,0 +1,86 @@
+---
+title: Get Started
+description: Requirements, installation, and a first command for the Simply GitLab CLI.
+---
+
+## Requirements
+
+- Node.js 22 or later
+- A GitLab account on gitlab.com or a self-managed instance, and an access token
+
+## Install
+
+```sh
+npm install -g @simplysf/simply-cli
+```
+
+## Verify it worked
+
+```sh
+simply gitlab --help
+```
+
+## Get a token
+
+Create a personal access token under **Preferences › Access tokens** in GitLab, or a project or
+group access token from that project's or group's settings. Two scopes matter:
+
+| Scope      | What it allows                                           |
+| ---------- | -------------------------------------------------------- |
+| `read_api` | Everything on this site that reads. Nothing that writes. |
+| `api`      | Reads and writes.                                        |
+
+Start with `read_api`. It is not just a smaller permission — it is the only thing that makes a
+write structurally impossible, which matters as soon as a script or an agent is running these
+commands. See [Write safety](/guides/write-safety/).
+
+## Connect to your instance
+
+Every command reads its connection settings from environment variables, from flags, or from a
+`.env` file passed with `-e/--env-file`:
+
+```
+GITLAB_TOKEN=glpat-...
+GITLAB_URL=https://gitlab.example.com   # omit entirely for gitlab.com
+```
+
+`GITLAB_URL` defaults to `https://gitlab.com`, so a gitlab.com user needs only the token. See
+[Credentials](/guides/credentials/) for precedence between flags, environment, and file, and for
+trusting an internal certificate authority.
+
+## First commands
+
+Find a project you can reach, then look at its open merge requests:
+
+```sh
+simply gitlab project list --membership
+simply gitlab mr list --project group/project
+```
+
+Add `--json` to either to get the raw API payload instead of the formatted table.
+
+## Naming a project
+
+Every project-scoped command takes `-p/--project`, which accepts a numeric id or the full path.
+Both of these are the same project:
+
+```sh
+simply gitlab mr list --project 1234
+simply gitlab mr list --project group/subgroup/project
+```
+
+The path is URL-encoded for you — do not encode it yourself. If you work in one project most of
+the time, set `GITLAB_PROJECT` and drop the flag.
+
+## Where to go next
+
+- The [Command Reference](/reference/) lists every command by topic, with its flags and examples.
+- [Credentials](/guides/credentials/) covers tokens, precedence, and certificates.
+- [Write safety](/guides/write-safety/) explains `--dry-run`, `GITLAB_READ_ONLY`, and why a
+  `read_api` token is the only one of those that actually binds.
+- [Scripts and agents](/guides/scripting/) covers the `--json` contract and exit codes.
+- [MCP server](/guides/mcp-server/) gives an AI agent the same capabilities as tools, read-only by
+  default.
+- Want to contribute? See
+  [CONTRIBUTING.md](https://github.com/SimplySF/simply-gitlab/blob/main/CONTRIBUTING.md) in the
+  repo.

package/docs/guides/baselines.md

@@ -0,0 +1,186 @@
+---
+title: Configuration baselines
+description: Hold many GitLab projects to one standard - export a baseline from a project you like, see what differs across the rest, and converge them.
+---
+
+Fifty projects drift. One was created before you settled on squash merges, someone unprotected
+`main` to fix something and never put it back, and two never had an approval rule at all. There is
+no answer to "are these the same?" short of opening fifty tabs.
+
+A baseline is a JSON file saying what those projects should have in common, and three commands that
+read it:
+
+| Command                       | Writes? | What it does                                         |
+| ----------------------------- | ------- | ---------------------------------------------------- |
+| `simply gitlab config export` | no      | Emits a config from a project you already like       |
+| `simply gitlab config plan`   | no      | Reports, per project, what differs from the baseline |
+| `simply gitlab config apply`  | yes     | Converges each project onto the baseline             |
+
+## Start by exporting
+
+Do not write the file by hand. Export the project that already looks right and delete what you do
+not care about:
+
+```sh
+simply gitlab config export --project group/api > baseline.json
+```
+
+The output is deliberately verbose — every supported key, not a curated subset — because deleting a
+line is easier than discovering that a key exists. Variables come out as metadata only: keys,
+scopes, and flags, never values.
+
+## Point it at the rest
+
+The exported file targets only the project it came from. Widen it on purpose:
+
+```json
+{
+  "version": 1,
+  "targets": {
+    "groups": ["platform"],
+    "exclude": ["platform/sandbox", "platform/archived-*"]
+  },
+  "project": {
+    "settings": {
+      "merge_method": "ff",
+      "squash_option": "default_on",
+      "only_allow_merge_if_pipeline_succeeds": true
+    },
+    "protectedBranches": [{ "name": "main", "allow_force_push": false }],
+    "approvalRules": [{ "name": "Two maintainers", "approvals_required": 2, "usernames": ["alice", "bob"] }]
+  }
+}
+```
+
+`targets.groups` expands through subgroups. `exclude` takes a trailing `*` to drop a whole subtree.
+A project the token cannot see is a hard error, not a silent omission — a baseline that quietly
+skipped six of fifty would leave those six wrong with nobody knowing to look.
+
+## Read the plan
+
+```sh
+simply gitlab config plan --config ./baseline.json
+```
+
+```
+Targets: 50 project(s), 1 group(s).
+
+platform/api
+  settings
+    ~ merge_method  merge → ff
+    ~ only_allow_merge_if_pipeline_succeeds  false → true
+  protectedBranches
+    ~ main.allow_force_push  true → false
+    - legacy   (not pruned; set "prune": true on this section to remove it)
+
+platform/worker
+  ✓ matches the baseline
+
+50 target(s): 31 match, 19 differ.
+```
+
+Three things in that output are worth understanding.
+
+**Only what you declared is 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:
+the blast radius is the set of keys you wrote down.
+
+**Drift you are not fixing is still shown.** `- legacy` is a protected branch that exists but is not
+in the config. By default nothing is deleted, and the line says so. Seeing what you are choosing not
+to correct is most of the value of running this across fifty projects.
+
+**A section can come back unsupported.** Approval rules, approval settings, and push rules are
+Premium/Ultimate. On an instance without them the section reports that and the rest still converges.
+
+## Apply it
+
+```sh
+simply gitlab config apply --config ./baseline.json --dry-run   # prints the plan, sends nothing
+simply gitlab config apply --config ./baseline.json
+```
+
+Apply executes exactly what the plan showed — the two are computed in one pass, so a preview is a
+guarantee rather than an approximation. A second run against a converged project sends no requests
+at all.
+
+Sections are applied in a fixed order: settings, protected branches, protected tags, approval
+settings, approval rules, push rules. That order exists because an approval rule scoped to `main`
+needs `main` protected before it can reference it.
+
+One project failing does not abandon the other forty-nine. There is no transaction across GitLab
+endpoints, so a project that fails part-way keeps the sections already applied; the summary says
+where it stopped, and `plan` afterwards shows what is left.
+
+## Per-project exceptions
+
+`overrides` is keyed by project path:
+
+```json
+"overrides": {
+  "platform/legacy-api": {
+    "project": {
+      "settings": { "merge_method": "merge" },
+      "approvalRules": [{ "name": "Two maintainers", "approvals_required": 1 }]
+    }
+  }
+}
+```
+
+Lists merge by a natural key — `name` for branches, tags, and rules; `key` plus `environment_scope`
+for variables — so an override adjusts one entry rather than restating the array. The rule above
+changes one number and inherits the usernames from the baseline.
+
+Set `"$replace": true` on a section to swap the list wholesale instead, for the project that needs
+genuinely different rules rather than adjusted ones.
+
+## Turning on pruning
+
+By default the config adds and corrects; it never deletes. When you are ready for a section to be
+authoritative, opt in:
+
+```json
+"protectedBranches": {
+  "prune": true,
+  "entries": [{ "name": "main", "allow_force_push": false }]
+}
+```
+
+Now an undeclared protected branch is removed. Adopt this section by section, after `plan` has shown
+you what it would take away — a first run against fifty existing projects with everything pruning
+could remove protections that predate the config.
+
+## Checking for drift in CI
+
+```sh
+simply gitlab config plan --config ./baseline.json --fail-on-drift
+```
+
+Exits `1` when anything differs, so a scheduled job tells you something drifted without anyone
+reading the output. `--json` returns the whole plan as structured data if you would rather track it
+over time:
+
+```sh
+simply gitlab config plan --config ./baseline.json --json | jq '.summary'
+```
+
+## CI/CD variables are reported, not written
+
+The config can declare which variables must exist and what flags they carry. `plan` reports the ones
+that are missing or wrong; `apply` does not touch them.
+
+That is the API, not caution. Creating a variable requires a value, and so does updating one — even
+to change `masked` from false to true. A variable created as `masked_and_hidden` will not return its
+value at all. There is no honest way to reconcile secrets from a file that, by design, holds none.
+
+Knowing that six projects are missing `DEPLOY_ENV` is still the question people actually ask; setting
+it is a person's job.
+
+## From an agent
+
+The MCP server exposes `gitlab_config_plan` and `gitlab_config_export`, so you can ask an agent
+"which of our projects are missing the two-approval rule?" and get an answer.
+
+There is deliberately no tool that applies a baseline. Changing settings across fifty projects is a
+deployment, not a tool call, and belongs to a person with the plan in front of them. An agent that
+should apply one can run the CLI, where it is a shell command you can see and approve. See the
+[MCP server guide](/guides/mcp-server/).

package/docs/guides/credentials.md

@@ -0,0 +1,100 @@
+---
+title: Credentials
+description: How the Simply GitLab CLI finds its connection settings, which token scope to use, and how flags, environment variables, and an env file take precedence.
+---
+
+Connection settings come from environment variables, from flags, or from a `.env` file named with
+`-e/--env-file`. Only GitLab connection variables are read from that file; anything else in it is
+ignored.
+
+```
+GITLAB_TOKEN=glpat-...
+GITLAB_URL=https://gitlab.example.com   # omit entirely for gitlab.com
+```
+
+There are only two settings, and one of them has a default — `GITLAB_URL` is `https://gitlab.com`
+unless you say otherwise. A gitlab.com user needs the token and nothing else.
+
+## Tokens and scopes
+
+The token is a personal access token (**Preferences › Access tokens**), a project access token, or
+a group access token. All three work the same way; the CLI sends whichever you give it as GitLab's
+`PRIVATE-TOKEN` header.
+
+| Scope      | Covers                                      |
+| ---------- | ------------------------------------------- |
+| `read_api` | Every read command on this site. No writes. |
+| `api`      | Reads and writes.                           |
+
+Prefer `read_api` and reach for `api` only when you mean to change something — see
+[Write safety](/guides/write-safety/) for why that distinction carries more weight than it looks
+like it should.
+
+OAuth 2 tokens are not supported: GitLab accepts those only as `Authorization: Bearer`, and this
+CLI runs no OAuth flow.
+
+## Precedence
+
+Explicit flags beat the environment, which beats the file's contents. That ordering is what makes
+the two-file arrangement in [Write safety](/guides/write-safety/) work: a `read_api` file can be
+the default, and a write-capable one is named explicitly for the one command that needs it.
+
+```sh
+simply gitlab mr list -e ~/gitlab.env --project group/project
+simply gitlab mr update -e ~/gitlab-write.env --project group/project --mr 42 --state close
+```
+
+A variable exported as an empty string does not outrank the file. `export GITLAB_TOKEN=` in a
+wrapper script would otherwise discard the real token and fail as though nothing were configured.
+
+## Naming a project
+
+Not a credential, but it belongs in the same shell profile. `GITLAB_PROJECT` sets the default for
+`-p/--project`:
+
+```sh
+export GITLAB_PROJECT=group/subgroup/project
+simply gitlab mr list
+```
+
+A project is named by numeric id or full path, and the path is URL-encoded for you.
+
+## Self-managed instances
+
+Set `GITLAB_URL` to the instance origin. A subpath is kept, because self-managed instances are
+routinely served from one:
+
+```
+GITLAB_URL=https://example.com/gitlab
+```
+
+One thing to watch: pasting a **project** URL from gitlab.com — `https://gitlab.com/group/project`
+— sets the instance, not the project. The CLI keeps only the origin in that case, since gitlab.com
+has no subpath. On a self-managed host it cannot tell a subpath from a project path, so give it the
+instance root and name the project with `--project`.
+
+## Certificate verification
+
+Certificate verification is always on. For an instance behind an internal or agency certificate
+authority, trust that CA rather than disabling verification:
+
+```sh
+NODE_EXTRA_CA_CERTS=/path/to/ca.pem simply gitlab project list
+```
+
+A `GITLAB_SSL_VERIFY=false` carried over from other GitLab tooling is rejected with an error rather
+than silently ignored, so nobody ends up believing verification is off when it is on, or the
+reverse.
+
+## Checking what you're connected as
+
+There is no `whoami` command. The cheapest check is a list you expect to be non-empty:
+
+```sh
+simply gitlab project list --membership --limit 5
+```
+
+A wrong or expired token comes back as an authentication error with exit code `3`. A `403` on a
+command that changes data says the token may be `read_api`-scoped, or that your role on the project
+does not permit the change — so a refused write is distinguishable from a genuine permissions
+problem.

package/docs/guides/scripting.md

@@ -0,0 +1,122 @@
+---
+title: Scripts and agents
+description: The output contract that makes the Simply GitLab CLI safe to drive from a shell script or an AI agent - raw JSON, stable exit codes, honest truncation, no prompts.
+---
+
+The CLI is designed for two callers at once: a person at a terminal, and a script or AI agent
+running it as shell commands. The defaults serve the person; a small, stable contract serves the
+script.
+
+## `--json` returns the raw API payload
+
+Every command accepts `--json`, without exception. The output is the unmodified response from the
+GitLab API — the full object, not the curated subset the table shows — so anything the API exposes
+is reachable with `jq`, and the payload shape is GitLab's contract rather than this CLI's.
+
+```sh
+simply gitlab mr view --project group/project --mr 42 --json | jq -r '.detailed_merge_status'
+```
+
+## Lists tell you when they were cut short
+
+Every list command follows pages up to `--limit`, so there is no single response to hand back.
+They return an envelope instead:
+
+```json
+{ "items": [...], "total": 500, "pages": 3, "complete": false }
+```
+
+The elements inside `items` are still raw API objects. **`complete: false` means `--limit` cut the
+results short** and more exist, so a caller can detect truncation without counting rows. `total` is
+present only when GitLab reports one — keyset-paginated endpoints and very large result sets omit
+it, so treat a missing `total` as unknown rather than zero.
+
+```sh
+out=$(simply gitlab mr list --project group/project --state all --limit 100 --json)
+if [ "$(jq -r .complete <<<"$out")" = "false" ]; then
+  echo "more than 100 merge requests; raise --limit" >&2
+fi
+```
+
+## Exit codes and errors
+
+Errors carry no stack trace and map to stable exit codes:
+
+| Exit code | Meaning                                                    |
+| --------- | ---------------------------------------------------------- |
+| `0`       | Success                                                    |
+| `2`       | Configuration or usage problem, e.g. a missing token       |
+| `3`       | Authentication or authorization failure                    |
+| `1`       | Anything else, including an API error or a network failure |
+
+Under `--json`, a failure is written as one JSON object on **stderr** and stdout stays empty, so a
+caller that captures stdout never has to disambiguate an error from a payload. The object nests
+under an `error` key:
+
+```json
+{ "error": { "name": "HttpError", "message": "...", "exitCode": 1, "status": 404, "body": {} } }
+```
+
+`body` carries the API's own response when there was one. Every string in the object — the message
+and everything inside `body` — is scrubbed of any known credential value and of characters that
+could rewrite the terminal or hide text, so a response that quotes your token back at you does not
+put it on the stream.
+
+```sh
+if ! out=$(simply gitlab mr view --project group/project --mr 999 --json 2>err.json); then
+  case $? in
+    3) echo "credentials rejected";;
+    *) jq -r .error.message err.json;;
+  esac
+fi
+```
+
+## Address merge requests by `iid`
+
+A merge request has both an `id` and an `iid`. Both are bare integers, both appear in every
+payload, and the endpoints take the **`iid`** — the number in the web URL. Passing the wrong one
+does not fail: it addresses a different merge request in a different project that happens to share
+the number.
+
+The CLI validates the shape and refuses anything that is not a positive whole number, but it cannot
+catch a valid-looking wrong number. When scripting, read `iid` from the list output, never `id`:
+
+```sh
+simply gitlab mr list --project group/project --json | jq -r '.items[].iid'
+```
+
+## Keep payloads small
+
+`--simple` on `project list` returns a much smaller object. `--stat` on `commit diff` lists the
+changed files without the hunks. `--tail` on `ci job log` defaults to the last 200 lines, because a
+trace is regularly tens of megabytes and an agent pays for every token it reads:
+
+```sh
+simply gitlab ci job list --project group/project --scope failed --limit 5 --json \
+  | jq -r '.items[0].id' \
+  | xargs -I{} simply gitlab ci job log --project group/project --job {} --tail 50
+```
+
+## Retries are handled for you
+
+429 and 5xx responses retry with exponential backoff, honouring a capped `Retry-After`. DNS
+failures and certificate problems do not retry, because another attempt cannot fix them. A script
+does not need its own retry loop around these commands.
+
+## Never interactive
+
+No command prompts or blocks on stdin, and there is no `--confirm` flag to hang on. Every write
+takes `--dry-run` instead. See [Write safety](/guides/write-safety/) for the full set of layers and
+the two-credential-file arrangement that keeps an agent's normal loop read-only.
+
+## Help is discovery
+
+`--help` output is generated from the command classes and written to be self-sufficient, so an
+agent can discover flags and examples the same way a person does:
+
+```sh
+simply gitlab mr --help
+simply gitlab mr create --help
+```
+
+The same text, for every command, is on the [Command Reference](/reference/) pages.

package/docs/guides/write-safety.md

@@ -0,0 +1,121 @@
+---
+title: Write safety
+description: The layers between a Simply GitLab command and a change to your repository, which of them is a real boundary, and why CI variable values are hidden by default.
+---
+
+Six commands change data — `branch create`, `file create`, `file update`, `commit create`,
+`mr create`, and `mr update`. Nothing in this CLI deletes anything. Those six sit behind several
+layers, and only the last is a real boundary.
+
+## No `--confirm`, deliberately
+
+Every write here either creates something or edits a merge request, and both are recoverable: a
+branch can be deleted, a file can be committed over, a closed merge request can be reopened.
+Requiring a confirmation for actions like those would train you to pass it always, at which point
+it protects nothing while still implying that it does.
+
+So there is no `--confirm` flag anywhere in this CLI. The first command that irreversibly destroys
+something is the one that brings it back.
+
+## `--dry-run`
+
+Accepted by all six. It prints the exact request body that would be sent and sends nothing, which
+is the cheapest way to see what is about to happen:
+
+```sh
+simply gitlab mr create --project group/project \
+  --source-branch feature/thing --target-branch main --title "feat: the thing" --dry-run
+```
+
+```
+Dry run — not sent. Request body:
+{
+  "source_branch": "feature/thing",
+  "target_branch": "main",
+  "title": "feat: the thing"
+}
+```
+
+## `--last-commit-id` on a file update
+
+`file update` replaces the whole file; there is no partial edit. That makes a lost-update race real
+whenever two people or two runs touch the same file. `file view` reports the file's last commit,
+and passing it back makes GitLab reject the write if anything changed meanwhile:
+
+```sh
+simply gitlab file view --project group/project --path README.md --ref main
+# Last commit: 9a1b2c3
+
+simply gitlab file update --project group/project --path README.md --branch main \
+  --content-file ./README.md --message "docs: refresh" --last-commit-id 9a1b2c3
+```
+
+Without it, the last writer silently wins.
+
+## `GITLAB_READ_ONLY`
+
+Set it to `1`, `true`, `yes`, or `on` and every write command refuses before making any request.
+Reads are unaffected. This guards against misconfiguration: the wrong credential file, the wrong
+project, the wrong context. It is not a security boundary, because anything that can run commands
+can also unset an environment variable.
+
+## A `read_api` token
+
+This is the only layer that actually binds. A `read_api`-scoped token cannot create, edit, or push
+anything — GitLab refuses server-side, regardless of what this CLI sends or what any caller is
+persuaded to attempt.
+
+That matters most when an AI agent drives the CLI, because merge request descriptions, commit
+messages, and file contents are written by anyone who can push, and an agent reading that text
+cannot reliably tell instructions from content. The arrangement worth adopting is two credential
+files:
+
+```
+~/gitlab.env        # read_api token — what the agent uses by default
+~/gitlab-write.env  # api token — passed explicitly, by a person
+```
+
+```sh
+simply gitlab mr list -e ~/gitlab.env --project group/project
+simply gitlab mr update -e ~/gitlab-write.env --project group/project --mr 42 --state close
+```
+
+The agent's normal loop is then structurally incapable of changing anything, and a write becomes a
+deliberate act.
+
+## CI variable values are hidden
+
+`simply gitlab ci variable list` replaces every value with `<hidden>`, in the table and under
+`--json` alike:
+
+```sh
+simply gitlab ci variable list --project group/project
+```
+
+```
+KEY         SCOPE  TYPE     PROTECTED  MASKED  VALUE
+──────────  ─────  ───────  ─────────  ──────  ────────
+DEPLOY_KEY  *      env_var  yes        yes     <hidden>
+
+Showing 1 of 1 variable(s).
+Values are hidden. Pass --reveal to print them.
+```
+
+This is worth explaining, because GitLab's own API does not do this. `GET /projects/:id/variables`
+returns **every** value in clear text — including the ones marked "masked", since masking only
+hides a value in job logs, not from the API. Those values are deploy keys, signing certificates,
+and production credentials, and the usual reason to list them is to see _which_ exist, not to read
+them.
+
+`--reveal` prints them. It exists on the CLI and has no equivalent in the
+[MCP server](/guides/mcp-server/), deliberately: a value revealed to a person is on their screen,
+and a value revealed to an agent is in a context window, a transcript, and whatever that agent
+writes next.
+
+## Untrusted text is stripped
+
+Merge request titles and descriptions, commit messages, repository file contents, and CI job traces
+are all written by whoever can push to a project or open a merge request. Every one of them is
+stripped of control characters before it is printed, so an escape sequence cannot make your
+terminal show something other than what the API returned — and your token is redacted from every
+error message and response body.