From 09845483f2c37ba9cf0c3d9768cff06b199311bb Mon Sep 17 00:00:00 2001 From: Donald Merand Date: Fri, 5 Jun 2026 11:36:26 -0400 Subject: [PATCH 1/7] Document pre-submit workflow and local dev in AGENTS.md + docs/LOCAL_DEV.md --- AGENTS.md | 43 +++++++++++++++++++++++++++++++++++++++++++ docs/LOCAL_DEV.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 AGENTS.md create mode 100644 docs/LOCAL_DEV.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000000..eb51a4a7653 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,43 @@ +# Working in Shopify CLI + +Guidance for contributors and coding agents to get a change green in CI with the fewest round-trips. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for changesets/versioning and [`docs/LOCAL_DEV.md`](./docs/LOCAL_DEV.md) for running the CLI locally. + +## Before you push: `pnpm pre-ci` + +Run the local subset of the PR pipeline before pushing: + +```bash +pnpm pre-ci # or: dev pre-ci +``` + +It runs, in CI-parity order: `type-check`, `lint`, `build`, `knip`, the graphql and OCLIF/docs codegen freshness checks, and unit tests — and prints which CI-only gates it skips (e2e, type-diff, breaking-change detection) and why. It mirrors CI's full targets, so green locally implies green in CI; it is slower than the affected-only `dev check`. + +The gate list lives in [`bin/ci-gates.js`](./bin/ci-gates.js) and is kept in sync with `.github/workflows/tests-pr.yml` by `pnpm check-ci-gates` (enforced by the `CI gate manifest` CI job). When you add or change a CI gate, update that manifest. + +## After changing commands, flags, or GraphQL queries: `pnpm codegen` + +Generated files are gated in CI (`Check OCLIF manifests & readme & docs`, `Check graphql-codegen has been run`). Regenerate and commit them: + +```bash +pnpm codegen # regenerate everything +pnpm codegen:check:oclif # regenerate + verify the tree is clean (as CI does) +pnpm codegen:check:graphql +``` + +## Linting + +Use the repo's lint command, not `eslint` directly: + +```bash +pnpm lint # nx-driven; matches the CI "Lint" job +pnpm lint:fix # auto-fix +``` + +Invoking `eslint ` directly can report problems CI does not enforce (and CI lints project sources, not root `bin/` scripts). Repo-specific lint conventions are implemented in [`packages/eslint-plugin-cli/rules/`](./packages/eslint-plugin-cli/rules) (for example, `no-vi-manual-mock-clear` — Vitest resets mocks automatically, so do not clear them by hand). Check there when a rule is unfamiliar rather than guessing. + +## Tests + +```bash +pnpm test # full vitest run (single env; CI runs a node/OS matrix) +pnpm vitest run path/to/file.test.ts # a single file +``` diff --git a/docs/LOCAL_DEV.md b/docs/LOCAL_DEV.md new file mode 100644 index 00000000000..df75060591e --- /dev/null +++ b/docs/LOCAL_DEV.md @@ -0,0 +1,42 @@ +# Local development + +How to set up and run Shopify CLI from a checkout. For the pre-submit workflow and lint/codegen guidance, see [`../AGENTS.md`](../AGENTS.md). + +## Setup + +```bash +dev up # installs the pinned Node + pnpm, dependencies, GraphQL schemas, and Playwright +``` + +`dev up` pins the same Node and pnpm versions CI uses (`dev.yml` ↔ `tests-pr.yml`, enforced by `pnpm check-ci-gates`), so your local runtime matches CI. + +## Running the CLI + +```bash +pnpm shopify # builds the cli, then runs it (e.g. pnpm shopify app dev) +dev shopify # same, via the dev command +``` + +`pnpm shopify` rebuilds the `cli` package first, so it reflects your latest changes. + +## Local service environment + +When developing against local services rather than production: + +```bash +SHOPIFY_SERVICE_ENV=local +SHOPIFY_CLI_NEVER_USE_PARTNERS_API=1 +``` + +- **Admin URLs**: in local mode the CLI maps `{store}.my.shop.dev` to `admin.shop.dev/store/{store}` — see `packages/cli-kit/src/public/node/context/fqdn.ts`. +- **Organization**: use organization ID `1` for local development. + +## Theme check + +The `theme check` command wraps [`@shopify/theme-check-node`](https://github.com/Shopify/theme-tools). Entry point: `packages/theme/src/cli/commands/theme/check.ts`. + +## Before opening a PR + +- Run `pnpm pre-ci` (see [`../AGENTS.md`](../AGENTS.md)). +- After changing commands, flags, or GraphQL queries, run `pnpm codegen` and commit the regenerated files. +- For changesets and bump types, see [`../CONTRIBUTING.md`](../CONTRIBUTING.md). From b0e24863cb6923a69e01ac31bbdd267db45643cb Mon Sep 17 00:00:00 2001 From: Donald Merand Date: Fri, 5 Jun 2026 14:43:04 -0400 Subject: [PATCH 2/7] Drop org-id default from local dev docs --- docs/LOCAL_DEV.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/LOCAL_DEV.md b/docs/LOCAL_DEV.md index df75060591e..123eb720009 100644 --- a/docs/LOCAL_DEV.md +++ b/docs/LOCAL_DEV.md @@ -29,7 +29,6 @@ SHOPIFY_CLI_NEVER_USE_PARTNERS_API=1 ``` - **Admin URLs**: in local mode the CLI maps `{store}.my.shop.dev` to `admin.shop.dev/store/{store}` — see `packages/cli-kit/src/public/node/context/fqdn.ts`. -- **Organization**: use organization ID `1` for local development. ## Theme check From 4f34e8c8f4ca211b7524912919561c3c430aba54 Mon Sep 17 00:00:00 2001 From: Donald Merand Date: Fri, 5 Jun 2026 15:12:48 -0400 Subject: [PATCH 3/7] Make AGENTS.md the source of truth; symlink .claude/CLAUDE.md to it --- .claude/CLAUDE.md | 3 +-- AGENTS.md | 3 +++ 2 files changed, 4 insertions(+), 2 deletions(-) mode change 100644 => 120000 .claude/CLAUDE.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md deleted file mode 100644 index fe7f29ba506..00000000000 --- a/.claude/CLAUDE.md +++ /dev/null @@ -1,2 +0,0 @@ -See @../.cursor/rules/base.mdc for information on your desired behavior. -See @../.cursor/rules/docs.mdc for details on Shopify CLI architecture and conventions. diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md new file mode 120000 index 00000000000..be77ac83a18 --- /dev/null +++ b/.claude/CLAUDE.md @@ -0,0 +1 @@ +../AGENTS.md \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index eb51a4a7653..1372cea4d07 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,6 @@ +See @.cursor/rules/base.mdc for your desired behavior. +See @.cursor/rules/docs.mdc for Shopify CLI architecture and conventions. + # Working in Shopify CLI Guidance for contributors and coding agents to get a change green in CI with the fewest round-trips. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for changesets/versioning and [`docs/LOCAL_DEV.md`](./docs/LOCAL_DEV.md) for running the CLI locally. From 2436affc645136759033c6bb1119d947c5c714d9 Mon Sep 17 00:00:00 2001 From: Donald Merand Date: Mon, 8 Jun 2026 09:29:24 -0400 Subject: [PATCH 4/7] Integrate DX docs into existing docs/ tree and CI skills - AGENTS.md becomes a thin router into docs/ and .agents/skills - Move local-service-dev facts to docs/cli/local-development.md (indexed) - Fold pre-ci/codegen/check-ci-gates into get-started + CI contracts doc - Reconcile pnpm pre-ci (full parity) with cli-pre-submit-ci minimal-derived default - Remove orphan docs/LOCAL_DEV.md --- .../_shared/shopify-cli-ci-repo-contracts.md | 6 +++ .agents/skills/cli-pre-submit-ci/SKILL.md | 4 +- AGENTS.md | 49 +++++-------------- docs/LOCAL_DEV.md | 41 ---------------- docs/README.md | 1 + docs/cli/get-started.md | 5 ++ docs/cli/local-development.md | 18 +++++++ 7 files changed, 44 insertions(+), 80 deletions(-) delete mode 100644 docs/LOCAL_DEV.md create mode 100644 docs/cli/local-development.md diff --git a/.agents/skills/_shared/shopify-cli-ci-repo-contracts.md b/.agents/skills/_shared/shopify-cli-ci-repo-contracts.md index 9dae6696d24..71237d29ba8 100644 --- a/.agents/skills/_shared/shopify-cli-ci-repo-contracts.md +++ b/.agents/skills/_shared/shopify-cli-ci-repo-contracts.md @@ -25,6 +25,12 @@ For normal PR CI work, start with `.github/workflows/tests-pr.yml`. - Generated outputs are often part of the required change set when a workflow step verifies cleanliness after regeneration. - `dev.yml` is a useful local workflow entrypoint, but workflow YAML is the source of truth for what CI actually enforces. +## Local pre-submit tooling + +- `pnpm pre-ci` runs the local subset of PR gates at full CI parity (type-check, lint, build, knip, codegen freshness, unit tests). It is heavier than routine work needs; prefer the minimal diff-derived set below, and reach for `pre-ci` when the user wants full confidence before a high-risk push. +- Codegen freshness is single-sourced in `package.json`: `pnpm codegen` regenerates all generated files; `pnpm codegen:check:graphql` / `:oclif` regenerate and assert a clean tree. The workflow's `graphql-schema` and `oclif-checks` jobs call these scripts, so local and CI cannot drift. +- `bin/ci-gates.js` is the source of truth mapping each `tests-pr.yml` job to a `pre-ci` command or a `ci-only` reason. `pnpm check-ci-gates` (CI job `CI gate manifest`) fails if a workflow job is unclassified or if the Node/pnpm versions in `dev.yml` and `tests-pr.yml` disagree. + ## Gotchas - Do not guess from a check name alone when the workflow or job definition is available. diff --git a/.agents/skills/cli-pre-submit-ci/SKILL.md b/.agents/skills/cli-pre-submit-ci/SKILL.md index 98870d67742..ed1c1a5c245 100644 --- a/.agents/skills/cli-pre-submit-ci/SKILL.md +++ b/.agents/skills/cli-pre-submit-ci/SKILL.md @@ -35,7 +35,7 @@ If the diff clearly maps to a narrow family, keep the investigation narrow. |---|---| | docs/config/wiring only, with no obvious workflow-enforced generator family | **stop there unless contradicted**: run lightweight sanity checks only (`git diff --check`, validate changed symlink targets, validate local markdown links if relevant); do not full-read large workflow/script files | | user is at PR time (`submit`, `open`, `update`, `restack`) | advisory mode: suggest minimal checks, staging needs, and likely CI risk; ask before running anything substantial | -| user asks what to run before push | recommend the minimal high-signal checks implied by the workflow | +| user asks what to run before push | recommend the minimal high-signal checks implied by the workflow; mention `pnpm pre-ci` as the full-parity option for a high-risk push | | user asks what to commit or stage | reproduce the relevant generator/check path, then inspect git status and diffs | | user explicitly asks to run checks | run the minimal derived set, not the whole world | @@ -75,7 +75,7 @@ After any generator, freshness check, or lightweight sanity pass: ## Gotchas -- At PR time, do **not** automatically run the full workflow-equivalent validation set unless the user asks. +- At PR time, do **not** automatically run the full workflow-equivalent validation set unless the user asks. `pnpm pre-ci` is that full set — offer it for high-risk pushes, but default to the minimal derived checks. - `dev.yml` is a useful local entrypoint, but workflow YAML is the source of truth for what CI enforces. - Broad generated diffs are not automatically wrong; distinguish required churn from suspicious churn. - Do not stop at “run this command.” Explain what likely needs staging. diff --git a/AGENTS.md b/AGENTS.md index 1372cea4d07..837002bec3e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,44 +3,19 @@ See @.cursor/rules/docs.mdc for Shopify CLI architecture and conventions. # Working in Shopify CLI -Guidance for contributors and coding agents to get a change green in CI with the fewest round-trips. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for changesets/versioning and [`docs/LOCAL_DEV.md`](./docs/LOCAL_DEV.md) for running the CLI locally. +Entry point for contributors and coding agents. Canonical docs live under [`docs/`](./docs/README.md) and agent skills under [`.agents/skills/`](./.agents/skills); this file routes to them rather than restating them. -## Before you push: `pnpm pre-ci` +## Before you push -Run the local subset of the PR pipeline before pushing: +- Derive the minimal checks for your diff with the [`cli-pre-submit-ci`](./.agents/skills/cli-pre-submit-ci/SKILL.md) skill. For full local CI parity (slower), run `pnpm pre-ci`. +- After changing commands, flags, or GraphQL queries, run `pnpm codegen` and commit the regenerated files. +- `pnpm check-ci-gates` keeps the local gate list ([`bin/ci-gates.js`](./bin/ci-gates.js)) and pinned tool versions in sync with the workflow. -```bash -pnpm pre-ci # or: dev pre-ci -``` +## Key docs -It runs, in CI-parity order: `type-check`, `lint`, `build`, `knip`, the graphql and OCLIF/docs codegen freshness checks, and unit tests — and prints which CI-only gates it skips (e2e, type-diff, breaking-change detection) and why. It mirrors CI's full targets, so green locally implies green in CI; it is slower than the affected-only `dev check`. - -The gate list lives in [`bin/ci-gates.js`](./bin/ci-gates.js) and is kept in sync with `.github/workflows/tests-pr.yml` by `pnpm check-ci-gates` (enforced by the `CI gate manifest` CI job). When you add or change a CI gate, update that manifest. - -## After changing commands, flags, or GraphQL queries: `pnpm codegen` - -Generated files are gated in CI (`Check OCLIF manifests & readme & docs`, `Check graphql-codegen has been run`). Regenerate and commit them: - -```bash -pnpm codegen # regenerate everything -pnpm codegen:check:oclif # regenerate + verify the tree is clean (as CI does) -pnpm codegen:check:graphql -``` - -## Linting - -Use the repo's lint command, not `eslint` directly: - -```bash -pnpm lint # nx-driven; matches the CI "Lint" job -pnpm lint:fix # auto-fix -``` - -Invoking `eslint ` directly can report problems CI does not enforce (and CI lints project sources, not root `bin/` scripts). Repo-specific lint conventions are implemented in [`packages/eslint-plugin-cli/rules/`](./packages/eslint-plugin-cli/rules) (for example, `no-vi-manual-mock-clear` — Vitest resets mocks automatically, so do not clear them by hand). Check there when a rule is unfamiliar rather than guessing. - -## Tests - -```bash -pnpm test # full vitest run (single env; CI runs a node/OS matrix) -pnpm vitest run path/to/file.test.ts # a single file -``` +- [Get started / setup and scripts](./docs/cli/get-started.md) +- [Local development against services](./docs/cli/local-development.md) +- [ESLint rules](./docs/cli/eslint-rules.md) +- [Testing strategy](./docs/cli/testing-strategy.md) +- [Cross-OS compatibility](./docs/cli/cross-os-compatibility.md) +- [Changesets and versioning](./CONTRIBUTING.md) diff --git a/docs/LOCAL_DEV.md b/docs/LOCAL_DEV.md deleted file mode 100644 index 123eb720009..00000000000 --- a/docs/LOCAL_DEV.md +++ /dev/null @@ -1,41 +0,0 @@ -# Local development - -How to set up and run Shopify CLI from a checkout. For the pre-submit workflow and lint/codegen guidance, see [`../AGENTS.md`](../AGENTS.md). - -## Setup - -```bash -dev up # installs the pinned Node + pnpm, dependencies, GraphQL schemas, and Playwright -``` - -`dev up` pins the same Node and pnpm versions CI uses (`dev.yml` ↔ `tests-pr.yml`, enforced by `pnpm check-ci-gates`), so your local runtime matches CI. - -## Running the CLI - -```bash -pnpm shopify # builds the cli, then runs it (e.g. pnpm shopify app dev) -dev shopify # same, via the dev command -``` - -`pnpm shopify` rebuilds the `cli` package first, so it reflects your latest changes. - -## Local service environment - -When developing against local services rather than production: - -```bash -SHOPIFY_SERVICE_ENV=local -SHOPIFY_CLI_NEVER_USE_PARTNERS_API=1 -``` - -- **Admin URLs**: in local mode the CLI maps `{store}.my.shop.dev` to `admin.shop.dev/store/{store}` — see `packages/cli-kit/src/public/node/context/fqdn.ts`. - -## Theme check - -The `theme check` command wraps [`@shopify/theme-check-node`](https://github.com/Shopify/theme-tools). Entry point: `packages/theme/src/cli/commands/theme/check.ts`. - -## Before opening a PR - -- Run `pnpm pre-ci` (see [`../AGENTS.md`](../AGENTS.md)). -- After changing commands, flags, or GraphQL queries, run `pnpm codegen` and commit the regenerated files. -- For changesets and bump types, see [`../CONTRIBUTING.md`](../CONTRIBUTING.md). diff --git a/docs/README.md b/docs/README.md index 5e6e3c44c9b..4321490af04 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,6 +11,7 @@ The Shopify CLI is a tool for merchants, partners, and developers to interact wi The list below contains valuable resources for people interested in contributing to the CLI project in this repository. * [Get started](./cli/get-started.md) +* [Local development against services](./cli/local-development.md) * [Architecture](./cli/architecture.md) * [Conventions](./cli/conventions.md) * [Performance](./cli/performance.md) diff --git a/docs/cli/get-started.md b/docs/cli/get-started.md index 259eabda141..4e4a621f6e1 100644 --- a/docs/cli/get-started.md +++ b/docs/cli/get-started.md @@ -72,5 +72,10 @@ Besides the scripts for building and running the CLIs, there are others that mig - `pnpm lint:fix`: Runs ESLint and Prettier checks for all the packages and fixes the fixable issues. - `pnpm type-check`: Type-checks all the packagesusing the Typescript `tsc` tool. - `pnpm clean`: Removes the `dist` directory from all the packages. +- `pnpm pre-ci`: Runs the local subset of PR CI gates (type-check, lint, build, knip, codegen freshness, unit tests) at full parity with CI. Slower, for a high-risk push; for routine PRs derive the minimal checks for your diff (see the `cli-pre-submit-ci` agent skill). +- `pnpm codegen`: Regenerates all generated files (GraphQL types, OCLIF manifests, README, docs). Run after changing commands, flags, or queries, and commit the result. +- `pnpm check-ci-gates`: Verifies the local CI-gate manifest stays in sync with the GitHub Actions workflow. + +Prefer these scripts over invoking `eslint`/`prettier`/`tsc` directly: CI runs them through Nx over package sources, not over root `bin/` scripts. All the packages in the repository contain the above scripts so they can be executed too for an individual package. diff --git a/docs/cli/local-development.md b/docs/cli/local-development.md new file mode 100644 index 00000000000..586f581fcbc --- /dev/null +++ b/docs/cli/local-development.md @@ -0,0 +1,18 @@ +# Local development against services + +Most contributions run against production Shopify services. When developing against a local services stack, the CLI changes behavior based on the service environment. + +## Service environment + +- `SHOPIFY_SERVICE_ENV=local` +- `SHOPIFY_CLI_NEVER_USE_PARTNERS_API=1` + +In local mode the CLI maps a store's `{store}.my.shop.dev` host to `admin.shop.dev/store/{store}` — see `packages/cli-kit/src/public/node/context/fqdn.ts`. + +## Running the CLI + +See [Get started](./get-started.md) for building and running the CLI (`pnpm shopify `) and the available scripts. + +## Before opening a PR + +Derive the minimal pre-submit checks for your diff (see the `cli-pre-submit-ci` agent skill), or run `pnpm pre-ci` for full local CI parity. After changing commands, flags, or GraphQL queries, run `pnpm codegen` and commit the regenerated files. From a7d0153812fcf69f27fee7015a8d7794c54bba41 Mon Sep 17 00:00:00 2001 From: Donald Merand Date: Mon, 8 Jun 2026 09:57:32 -0400 Subject: [PATCH 5/7] Reference pre-ci:affected and lean the pre-submit skill on the gate manifest --- .agents/skills/_shared/shopify-cli-ci-repo-contracts.md | 2 +- .agents/skills/cli-pre-submit-ci/SKILL.md | 8 +++++--- AGENTS.md | 2 +- docs/cli/get-started.md | 3 ++- 4 files changed, 9 insertions(+), 6 deletions(-) diff --git a/.agents/skills/_shared/shopify-cli-ci-repo-contracts.md b/.agents/skills/_shared/shopify-cli-ci-repo-contracts.md index 71237d29ba8..aee77847a8d 100644 --- a/.agents/skills/_shared/shopify-cli-ci-repo-contracts.md +++ b/.agents/skills/_shared/shopify-cli-ci-repo-contracts.md @@ -27,7 +27,7 @@ For normal PR CI work, start with `.github/workflows/tests-pr.yml`. ## Local pre-submit tooling -- `pnpm pre-ci` runs the local subset of PR gates at full CI parity (type-check, lint, build, knip, codegen freshness, unit tests). It is heavier than routine work needs; prefer the minimal diff-derived set below, and reach for `pre-ci` when the user wants full confidence before a high-risk push. +- `pnpm pre-ci` runs the local subset of PR gates at full CI parity (type-check, lint, build, knip, codegen freshness, unit tests). `pnpm pre-ci:affected` runs the diff-scoped fast variant (nx/vitest affected; skips the codegen freshness checks unless the diff touches commands, flags, or GraphQL). Default to affected; reach for full `pre-ci` before a high-risk push. - Codegen freshness is single-sourced in `package.json`: `pnpm codegen` regenerates all generated files; `pnpm codegen:check:graphql` / `:oclif` regenerate and assert a clean tree. The workflow's `graphql-schema` and `oclif-checks` jobs call these scripts, so local and CI cannot drift. - `bin/ci-gates.js` is the source of truth mapping each `tests-pr.yml` job to a `pre-ci` command or a `ci-only` reason. `pnpm check-ci-gates` (CI job `CI gate manifest`) fails if a workflow job is unclassified or if the Node/pnpm versions in `dev.yml` and `tests-pr.yml` disagree. diff --git a/.agents/skills/cli-pre-submit-ci/SKILL.md b/.agents/skills/cli-pre-submit-ci/SKILL.md index ed1c1a5c245..c4d71fc29c3 100644 --- a/.agents/skills/cli-pre-submit-ci/SKILL.md +++ b/.agents/skills/cli-pre-submit-ci/SKILL.md @@ -35,14 +35,16 @@ If the diff clearly maps to a narrow family, keep the investigation narrow. |---|---| | docs/config/wiring only, with no obvious workflow-enforced generator family | **stop there unless contradicted**: run lightweight sanity checks only (`git diff --check`, validate changed symlink targets, validate local markdown links if relevant); do not full-read large workflow/script files | | user is at PR time (`submit`, `open`, `update`, `restack`) | advisory mode: suggest minimal checks, staging needs, and likely CI risk; ask before running anything substantial | -| user asks what to run before push | recommend the minimal high-signal checks implied by the workflow; mention `pnpm pre-ci` as the full-parity option for a high-risk push | +| user asks what to run before push | `pnpm pre-ci:affected` for a diff-scoped fast check, or the minimal high-signal checks implied by the workflow; `pnpm pre-ci` for full parity before a high-risk push | | user asks what to commit or stage | reproduce the relevant generator/check path, then inspect git status and diffs | | user explicitly asks to run checks | run the minimal derived set, not the whole world | ### 2) Resolve the contract for the relevant family Only do this if the diff class suggests a real CI-family mapping, or if the user asks for broader confidence. -Read sources in this order: +The gate list is already resolved in [`bin/ci-gates.js`](../../../bin/ci-gates.js) — each `tests-pr.yml` job mapped to its local command (full and affected) or a ci-only reason. Read it first; `pnpm pre-ci` / `pnpm pre-ci:affected` run those gates, so most pre-submit work needs no per-diff YAML archaeology. + +When the manifest is not enough, resolve from the contract files in this order: 1. relevant `.github/workflows/*.yml` 2. `dev.yml` @@ -75,7 +77,7 @@ After any generator, freshness check, or lightweight sanity pass: ## Gotchas -- At PR time, do **not** automatically run the full workflow-equivalent validation set unless the user asks. `pnpm pre-ci` is that full set — offer it for high-risk pushes, but default to the minimal derived checks. +- At PR time, do **not** automatically run the full workflow-equivalent validation set unless the user asks. `pnpm pre-ci` is that full set; `pnpm pre-ci:affected` is the diff-scoped fast check (and skips the codegen freshness checks unless the diff touches commands, flags, or GraphQL). Default to affected or the minimal derived checks. - `dev.yml` is a useful local entrypoint, but workflow YAML is the source of truth for what CI enforces. - Broad generated diffs are not automatically wrong; distinguish required churn from suspicious churn. - Do not stop at “run this command.” Explain what likely needs staging. diff --git a/AGENTS.md b/AGENTS.md index 837002bec3e..77b57bdce04 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,7 @@ Entry point for contributors and coding agents. Canonical docs live under [`docs ## Before you push -- Derive the minimal checks for your diff with the [`cli-pre-submit-ci`](./.agents/skills/cli-pre-submit-ci/SKILL.md) skill. For full local CI parity (slower), run `pnpm pre-ci`. +- Run `pnpm pre-ci:affected` for a fast, diff-scoped pre-push check, or `pnpm pre-ci` for full CI parity before a high-risk push. The [`cli-pre-submit-ci`](./.agents/skills/cli-pre-submit-ci/SKILL.md) skill covers deriving the minimal set and what to stage. - After changing commands, flags, or GraphQL queries, run `pnpm codegen` and commit the regenerated files. - `pnpm check-ci-gates` keeps the local gate list ([`bin/ci-gates.js`](./bin/ci-gates.js)) and pinned tool versions in sync with the workflow. diff --git a/docs/cli/get-started.md b/docs/cli/get-started.md index 4e4a621f6e1..ddbd4b3f571 100644 --- a/docs/cli/get-started.md +++ b/docs/cli/get-started.md @@ -72,7 +72,8 @@ Besides the scripts for building and running the CLIs, there are others that mig - `pnpm lint:fix`: Runs ESLint and Prettier checks for all the packages and fixes the fixable issues. - `pnpm type-check`: Type-checks all the packagesusing the Typescript `tsc` tool. - `pnpm clean`: Removes the `dist` directory from all the packages. -- `pnpm pre-ci`: Runs the local subset of PR CI gates (type-check, lint, build, knip, codegen freshness, unit tests) at full parity with CI. Slower, for a high-risk push; for routine PRs derive the minimal checks for your diff (see the `cli-pre-submit-ci` agent skill). +- `pnpm pre-ci`: Runs the local subset of PR CI gates (type-check, lint, build, knip, codegen freshness, unit tests) at full parity with CI. Slower, for a high-risk push. +- `pnpm pre-ci:affected`: The diff-scoped fast variant for routine PRs (nx/vitest affected; skips codegen freshness checks unless the diff touches commands, flags, or GraphQL). - `pnpm codegen`: Regenerates all generated files (GraphQL types, OCLIF manifests, README, docs). Run after changing commands, flags, or queries, and commit the result. - `pnpm check-ci-gates`: Verifies the local CI-gate manifest stays in sync with the GitHub Actions workflow. From af49bfce06c40f0538a85c2599d02c88831485d1 Mon Sep 17 00:00:00 2001 From: Donald Merand Date: Mon, 8 Jun 2026 10:04:56 -0400 Subject: [PATCH 6/7] Skill-architect review: align cli-pre-submit-ci table/examples with the gate manifest and pre-ci modes --- .agents/skills/cli-pre-submit-ci/SKILL.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/.agents/skills/cli-pre-submit-ci/SKILL.md b/.agents/skills/cli-pre-submit-ci/SKILL.md index c4d71fc29c3..5f09abfd00d 100644 --- a/.agents/skills/cli-pre-submit-ci/SKILL.md +++ b/.agents/skills/cli-pre-submit-ci/SKILL.md @@ -59,11 +59,11 @@ Read only the files and script sections needed for the diff class you identified | Change shape | Inspect first | Likely response | |---|---|---| -| Command/flag/help surface | docs/manifests/readme freshness jobs | derive the generator path from workflow → scripts | -| GraphQL queries or schemas | schema/codegen freshness jobs | derive the schema fetch + codegen path | -| TypeScript implementation or exports | type-check, lint, knip, bundle jobs | focused tests plus required static checks | -| Test helpers, async UI, network/auth/callback logic | unit-test jobs and nearby tests | focused tests plus a CI-risk warning | -| Workflow files or CI plumbing | affected workflow definitions | validate the changed contract directly | +| Command/flag/help surface | OCLIF manifests/readme/docs freshness gate | run `pnpm codegen`; stage the regenerated manifests, README, and docs | +| GraphQL queries or schemas | graphql-codegen freshness gate | run `pnpm codegen` (or `pnpm codegen:check:graphql`); stage generated types | +| TypeScript implementation or exports | type-check, lint, knip, bundle jobs | `pnpm pre-ci:affected` (type-check, lint, knip, affected tests) | +| Test helpers, async UI, network/auth/callback logic | unit-test jobs and nearby tests | focused affected tests plus a CI-risk warning | +| Workflow files or CI plumbing | affected workflow definitions | validate the changed contract; `pnpm check-ci-gates` | ### 4) Finish with staging guidance After any generator, freshness check, or lightweight sanity pass: @@ -81,13 +81,12 @@ After any generator, freshness check, or lightweight sanity pass: - `dev.yml` is a useful local entrypoint, but workflow YAML is the source of truth for what CI enforces. - Broad generated diffs are not automatically wrong; distinguish required churn from suspicious churn. - Do not stop at “run this command.” Explain what likely needs staging. -- If the diff is docs/config/wiring only, do not escalate to heavyweight checks unless the workflow or the user gives a reason. -- For docs/config/wiring-only diffs, avoid full reads of large workflow or script files unless the diff clearly maps to an enforced CI family. +- For docs/config/wiring-only diffs, do not escalate to heavyweight checks or full reads of large workflow/script files unless the diff clearly maps to an enforced CI family. - If the change touches async/timing-heavy tests, local servers, callback flows, socket teardown, or workflow topology, warn that CI-only failures may still appear even after local checks pass. ## Examples -- "What should I run before I push this PR?" → derive the minimal checks from workflow → `dev.yml` → `package.json`, then recommend focused tests plus any required generators. +- "What should I run before I push this PR?" → `pnpm pre-ci:affected` for a fast diff-scoped check; if the diff touches commands, flags, or GraphQL, also run `pnpm codegen` and stage the output; `pnpm pre-ci` before a high-risk push. - "Submit this PR." → treat it as a pre-submit moment, suggest the minimal recommended checks and likely staging requirements first, and ask before running them. -- "Which generated files do I need to commit?" → reproduce the relevant generation path, inspect git status, and separate required generated output from optional churn. -- "I changed a command flag; what repo checks matter?" → start from the freshness job that enforces command-surface updates rather than from memory. +- "Which generated files do I need to commit?" → run the relevant `pnpm codegen` path, inspect git status, and separate required generated output from optional churn. +- "I changed a command flag; what repo checks matter?" → the OCLIF manifests/readme/docs freshness gate; run `pnpm codegen` and commit the regenerated files. From 39dc774bcfb0869c2b88c5aaa3d21c961564a43a Mon Sep 17 00:00:00 2001 From: Donald Merand Date: Mon, 8 Jun 2026 10:18:51 -0400 Subject: [PATCH 7/7] Fix AGENTS.md router framing to match that it summarizes commands --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 77b57bdce04..d79d54bbe4d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,7 +3,7 @@ See @.cursor/rules/docs.mdc for Shopify CLI architecture and conventions. # Working in Shopify CLI -Entry point for contributors and coding agents. Canonical docs live under [`docs/`](./docs/README.md) and agent skills under [`.agents/skills/`](./.agents/skills); this file routes to them rather than restating them. +Entry point for contributors and coding agents. It summarizes the pre-submit commands below and links to the canonical material: docs under [`docs/`](./docs/README.md), agent skills under [`.agents/skills/`](./.agents/skills). ## Before you push