From 0e1f3d06d77e3d8ae7c644b0328d7b6342a64c5e Mon Sep 17 00:00:00 2001 From: SomeoneWithOptions Date: Thu, 22 Oct 2026 06:39:56 -0500 Subject: [PATCH] docs(agents): condense agents guide and move release runbook --- AGENTS.md | 163 +++++------------------------------------------- CONTRIBUTING.md | 2 +- 2 files changed, 16 insertions(+), 149 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7fe208c..7866d1f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,154 +1,21 @@ # AGENTS.md -Instructions for AI coding agents working in this repo. Single source of truth for Codex, Pi, Claude, Cursor, Copilot, opencode. Keep this file under 32 KiB so Codex loads it fully. Prefer editing this file over duplicating guidance elsewhere. +- Green = `make check`. Run `make docs` after any help text change. +- Releases: follow `.github/release-notes/README.md`. Tag `main` HEAD only; tags are immutable. -## Commands +## New commands -```sh -make check # single definition of green: fmt-check + vet + lint + test + test-race + cross + tidy-check + vuln -make build # ./bin/n8n -make smoke # version + help + completion sanity -make docs # regenerate docs/README.md from Cobra help (required when help text changes) -go test ./internal/docs -run TestDocsAreCurrent -update # same as make docs -go test -race -shuffle=on -count=1 ./... # order-independence check -``` +- Operation exists in `openapi.yml` or `openapi.upstream.yml` (match method + path): add client method + command, update `internal/coverage/manifest.json`. Never assume one spec is a superset of the other; never delete an op one instance stopped serving, mark it `retired`. +- No matching operation: CLI-native command with `Annotations: {"cliOnly": "true"}`, logic in its own `internal//` package, no manifest change. Precedent: `workflow diff`. +- New upstream ops go into new `planned` phases, never delivered ones. -## Release runbook (maintainer only) +## Rules -Default flow: tag `main` HEAD directly, wait for release run to finish, curate body via `gh release edit`. No extra PR or commit needed. - -```sh -# 1. Pre-flight (must be on up-to-date main and green) -git checkout main && git pull -make check - -# 2. Verify HEAD is the commit to release -git log --oneline --decorate -3 - -# 3. Tag main HEAD and push (triggers release.yml: checks -> dist -> publish -> install smoke) -git tag vX.Y.Z && git push origin vX.Y.Z - -# 4. Monitor release run -gh run list --workflow=Release --limit 1 -# poll status: -gh run view --json status,conclusion - -# 5. Curate release notes on GitHub (drop chore PRs, keep only user-facing feats/fixes) -gh release view vX.Y.Z --json body --jq .body -# edit notes file and apply: -gh release edit vX.Y.Z --notes-file /tmp/notes.md -gh release view vX.Y.Z --json body --jq .body -``` - -Rules: -- Tag target must be `main` HEAD (never an unmerged branch head). Release workflow fails off-branch tags fast. -- Tags cannot be deleted or updated (tag ruleset enforces immutability). -- Release notes body: keep only user-facing feats/fixes and the compare link. Strip chore PRs. - - -CI (`.github/workflows/ci.yml`) runs the same `make` targets on ubuntu/macos/windows. No logic lives in YAML that `make` cannot run locally. Integration tests stay off in CI (no secrets). - -## Project shape - -```text -cmd/n8n/ binary entry point only, thin -internal/cli/ Cobra commands; one file per group (tag.go, workflow.go) + *_test.go -internal/n8n/ typed API client; one file per resource + *_test.go -internal/config/ contexts, URL, credential resolution -internal/output/ JSON + human rendering (see internal/cli/output.go) -internal/confirm/ destructive-action guard (see internal/confirm/confirm.go) -internal/coverage/ endpoint manifest + contract tests (manifest.json is committed artifact) -internal/deps/ dependency allowlist (internal/deps/deps.go) -internal/docs/ command reference generated from Cobra help -internal/workflowdiff/ CLI-native diff engine (no spec operation behind it) -test/integration/ opt-in live tests, skip cleanly without env -docs/ generated from help; never hand-edit prose that duplicates help -``` - -`cmd/n8n/main.go` stays thin. Business behavior belongs in testable packages. Pass dependencies via `internal/cli.Options` (streams, config dir, env, keyring, prompt, interactivity, HTTP client). No package-level globals, no `init()` command registration. See `internal/cli/cli.go`. - -## Two tracks — pick one first - -### Track A: spec-backed command (default when an OpenAPI operation exists) - -Source of truth is the union contract: `openapi.yml` (target instance) + `openapi.upstream.yml` (docs instance). Both are gitignored. Committed artifact is `internal/coverage/manifest.json` with `availability: both | target-only | upstream-only | retired` (`retired` = declared by no current document, kept because older instances still serve it). - -Rules: - -- Confirm method, path, scope, params, body, response codes, schemas against whichever document declares the operation. -- Match operations by method + path with `{param}` normalized. Read `operationId` first, fall back to `x-eov-operation-id`. Never assume one server is a superset of the other. Never delete an implemented operation because one instance stopped serving it; when no document declares it any more, mark it `retired` (precedent: `/git-connections*`, replaced by `/promotions/*`). -- Add one typed client method in `internal/n8n/.go` + one Cobra command in `internal/cli/.go`. -- Update `manifest.json` (`command`, `availability`, phase). Coverage test cross-checks manifest against each document that declares the operation and skips cleanly when a document is absent. -- Upstream-only / target-only commands ship unconditionally. An instance lacking the module answers 404/503, which the CLI reports as "not available to you" with a `discover` pointer. Integration tests for such groups run by default and skip on 404/503. - -### Track B: CLI-native feature (when NO spec operation exists) - -Spec is the default source, not a gate. If no operation matches, build Track B. Never force-fit `manifest.json`, never invent an `operationId`. - -Rules: - -- Mark the command `Annotations: map[string]string{"cliOnly": "true"}` (precedent: `internal/cli/workflow_diff.go`). -- Do not touch `internal/coverage/manifest.json`. -- Compose existing client methods; put new logic in a new package (`internal//`), keep the Cobra wrapper thin. -- State in `Long` why this is CLI-side (what it composes, what it never mutates). -- Full shared contracts below still apply (help, output, confirm, secrets, tests, docs). -- Precedent: `n8n workflow diff` compares saved definitions across two contexts without any spec operation. See `internal/cli/workflow_diff.go`, `internal/workflowdiff/diff.go`. - -Decision rule: matching method + path in either spec -> Track A. Otherwise -> Track B. - -## Shared contracts (both tracks) - -### 1. Client (`internal/n8n/`) - -- Validate before transport: enums, limits, IDs, dates, strict JSON, 1 MiB input cap, unknown fields rejected. Never spend a round trip on what can fail locally. -- Escape every ID with `PathJoin` as one path segment (`internal/n8n/tag.go`). Encode queries with `url.Values.Encode`. -- Separate write documents from read models so read-only fields (`id`, timestamps, server-owned fields) are never sent back. Filter + report dropped fields on stderr (precedent: `WorkflowDocument.ForCreate/ForUpdate`). -- Pointers distinguish omitted vs `false` / `0` / `""` / `null`. Nil slice encodes as `[]`, never `null`. PATCH refuses an empty document; PUT documents full-replacement semantics. -- Keep open-ended payloads as `json.RawMessage` (workflow definitions, rows, metrics) + `Extra` map for unknown fields so `get --output json` round-trips losslessly. Decode polymorphic responses by shape, not by request. -- Redact secrets: redacted `String`/`GoString`/`MarshalJSON` + `slog.LogValuer` on credential types; strip server-echoed secrets from errors while keeping status/path/request ID; force non-conforming plaintext responses back to the sentinel (`**hidden**` family). Secrets never enter argv. - -Canonical simple example: `internal/n8n/tag.go` (115 lines). Complex examples: `internal/n8n/datatable.go` (filters, polymorphic rows), `internal/n8n/workflow.go` (raw definition + read-only filtering). - -### 2. CLI (`internal/cli/`) - -- Every command sets `Short` (imperative, one line), `Long` (what, when vs siblings, prereqs, side effects, output shape, next step), `Example` (copy-pasteable; two when interactive/non-interactive differ). Parent groups document workflow order (`list` first) and name the child to start with. -- Every flag usage states format + default + fallback (e.g. `--context`, `--url`, `--output`, `--yes`, `--input`). Never leave an empty usage string. Enforced by `TestHelpIsDescriptive` and `TestHelpSucceedsAtEveryLevel` in `internal/cli/help_test.go`. -- Shared flags: `instanceFlags` (`--context`, `--url`) via `Options.apiClient` (`internal/cli/instance.go`); `--output text|json` validated by `validateOutput` (`internal/cli/output.go`). -- stdout = machine-readable result only. stderr = diagnostics, prompts, confirmations, next-step hints. `--output json` is stable for scripts; text uses `text/tabwriter`. Never color redirected output. Empty success exits 0 with a stderr hint, not an error. -- Complex bodies: `--input FILE` + `--input -`, capped at 1 MiB, strict decode (reject unknown fields + trailing documents). Flag-based and JSON-based inputs are mutually exclusive; one is required where applicable. `--input -` (stdin) always requires `--yes` on mutating commands because stdin cannot answer a prompt. -- Errors restate the fix because agents act on stderr: 401 names `n8n auth login` (or `n8n auth status` when the credential comes from env); 403 names the scope + license + `n8n discover --resource ` with the plural key the instance filters on; 404/503 share one availability diagnostic; 409 names the conflict cause + remediation. See `apiError` in `internal/cli/instance.go` plus per-resource wrappers (e.g. `tagAPIError`). - -### 3. Destructive commands - -- Rule: interactive run asks, non-interactive refuses unless `--yes`. Missing terminal is never consent. Confirm before transport so refusal sends no request. See `internal/confirm/confirm.go`, usage in `internal/cli/tag.go:runTagDelete`. -- Prompt names the exact blast radius (tag removed from all workflows vs workflows deleted; remote-branch rewrite vs local overwrite; identities deleted; checkout loss). Stronger variant for `--force` / hard-delete paths. -- No client-side dry-run unless the API supports it. Server dry-run (e.g. data-table row `--dry-run`) prints "dry run, nothing was changed" and skips confirmation because nothing is deleted. - -### 4. Pagination - -- List commands expose `--limit`, `--cursor`, `--all`; offset-style resources use `--skip`/`--take`. Cap `--all` at 10,000 (`n8n.DefaultCollectLimit`). Preserve filters across pages. Stop on short page / reported total / cap so a server ignoring the cursor cannot loop. Offset + cursor are mutually exclusive. Reject `--all` with unbounded detailed data (e.g. execution `--include-data` must page explicitly). - -### 5. Dependencies (closed list) - -Allowed direct requires live in `internal/deps/deps.go:Allowed`: `cobra`, `pflag`, `go-keyring`, `x/sys`, `x/term` (runtime); `go-cmp`, `yaml.v3` (tests). Adding a module is a deliberate edit to that allowlist, not an implementation detail. Stdlib covers HTTP, JSON, `log/slog`, `text/tabwriter`, `mime/multipart`, `os.Root`, testing + `httptest`. No assertion / mocking / CLI-testing framework. `staticcheck` + `govulncheck` are `go tool` directives, never binary imports. - -## Tests (required per command) - -- Client: `httptest.Server` covering method, escaped path, query encoding, auth header, body, success decode, non-2xx, empty 204/201, malformed JSON, cancellation/timeout. -- CLI in-process (`Options` with injected streams + fake client/server): arg validation, exit code, stdout, stderr, JSON output, confirmation refusal before transport, `--input -` requiring `--yes`. -- Help: new paths added to `TestHelpSucceedsAtEveryLevel`; `TestHelpIsDescriptive` must pass (Short/Long/Example + flag usage). -- Pagination where applicable: two-page collection at both layers, filters preserved. -- Docs: run `make docs`; `TestDocsAreCurrent` fails when stale. -- Integration (`test/integration/`): opt-in, skip cleanly without env. Destructive paths require explicit env (e.g. `N8N_INTEGRATION_DESTRUCTIVE=1`) and use `n8n-cli-test-` prefix + timestamp with cleanup registered before the first assertion. Read-only where the resource is identity- or instance-wide (roles, users, LDAP/SSO settings, source-control push/pull, package import). Never read-modify-write a resource the test did not create. Union-contract groups skip on 404/503, never fail. - -## Common traps (from shipped phases) - -- Audit returns `[]` when clean (not `{}`) and has no `{"data": ...}` envelope; accept empty array, reject populated array rather than dropping it. -- Tag names cap at ~24 chars and report overlong as 409 "already exists" — help + 409 message must name both causes. -- Workflow create answers 200 (not 201); sending a read `id` back is `400 request/body/id is read-only`; `description: null` on read cannot be replayed — drop nulls the schema does not type as nullable. -- Data-table insert `returnType=count|id` answers `{"success":true,"insertedRows":n}` / `[{"id":n}]`, not the documented shapes; upsert with `returnData` answers a one-row array. Column type `json` was removed from the spec in 1.1.1; the CLI no longer accepts it. -- Folder list is offset (`skip`/`take`, `{count, data}`), not cursor; `sortBy` must be percent-encoded; only `create` accepts the literal project ID `personal`; `select: project|tags|parentFolder` 500s on some instances. -- `discoverHint` keys are the lowercase tag names the instance reports (`tags`, `datatable`, `sourcecontrol`, ...), not the CLI group spellings. -- `Promotions` and `GitConnections` share the `gitConnection:*` scope namespace — distinguish by served paths in `/discover`, not by scopes. -- Target instance `/api/v1/openapi.yml` can sit behind an auth proxy; when `make spec` returns HTML, use `n8n discover --output json` endpoints as availability evidence. Discover is scope-filtered, so "not listed" may mean "not visible to this key". -- `TestPhaseCounts` forbids adding ops to delivered phases; new upstream ops go into new phases as `planned`. +- Validate locally before any request. +- Never send read-only fields back; filter and report dropped fields on stderr. +- stdout = result only; diagnostics, prompts, and hints go to stderr. +- Destructive commands: prompt when interactive, refuse without `--yes` otherwise, before any request. `--input -` always requires `--yes`. +- Error messages state the fix (which command to run, which scope is missing). +- Secrets never enter argv, logs, or error output. +- New dependencies require editing `internal/deps/deps.go:Allowed`. No test or mocking frameworks. +- Each command needs client + CLI tests. Integration tests are opt-in, skip without env, and never mutate resources they did not create. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 961e92e..84b2c3b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,4 +54,4 @@ After publish, curate release notes to drop internal chore PRs and keep only use gh release edit vX.Y.Z --notes-file /tmp/notes.md ``` -See `AGENTS.md` or `.github/release-notes/README.md` for full runbook. +See `.github/release-notes/README.md` for full runbook.