@fantastic.dev/repo-gates 0.2.1-bootstrap.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +28 -0
  2. package/package.json +4 -4
  3. package/setup.md +111 -0
package/README.md CHANGED
@@ -7,6 +7,34 @@ secret-shaped strings, shadcn UI quality, coverage, and bundle size, plus a
7
7
  CI-parity drift detector and a PR docs-coverage gate. The engine is repo-agnostic; your policy
8
8
  lives in a single `repo-gates.config.json`.
9
9
 
10
+ ## Quick start
11
+
12
+ Give your coding agent this prompt:
13
+
14
+ ```text
15
+ Read https://github.com/FantasticDevHQ/repo-gates/blob/main/setup.md
16
+ and set up @fantastic.dev/repo-gates in this repository.
17
+ Enable applicable gates, wire check:all into CI, and verify the setup.
18
+ ```
19
+
20
+ The [agent setup guide](https://github.com/FantasticDevHQ/repo-gates/blob/main/setup.md)
21
+ covers inspection, initialization, policy review, and verification.
22
+
23
+ Or initialize it yourself from the repository root:
24
+
25
+ ```bash
26
+ npm install -D @fantastic.dev/repo-gates
27
+ npx repo-gates init
28
+ npm run check:all
29
+ ```
30
+
31
+ Use your repository's package manager. See [setup commands for npm, pnpm, Yarn,
32
+ and Bun](https://github.com/FantasticDevHQ/repo-gates/blob/main/setup.md#install-and-initialize)
33
+ and the [initialization reference](#quickstart) for details. `init` enables
34
+ applicable gates, including all six design-system rules for Tailwind v4 and
35
+ Shadscan for detected shadcn projects. Review the generated config and any
36
+ existing-code findings before committing.
37
+
10
38
  ## What it does
11
39
 
12
40
  `check-all` runs an ordered manifest of gates and reports them **quietly** — one
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/repo-gates",
3
- "version": "0.2.1-bootstrap.0",
3
+ "version": "0.2.2",
4
4
  "description": "Config-driven repo quality gates for turborepo (and any) monorepos: a quiet check:all orchestrator, CI-parity drift detector, a PR docs-coverage gate, and ratchet guards (file size, debt markers, circular imports, secrets, coverage, bundle size). The engine is repo-agnostic; policy lives in the consumer repo's config.",
5
5
  "keywords": [
6
6
  "turborepo",
@@ -50,7 +50,8 @@
50
50
  }
51
51
  },
52
52
  "files": [
53
- "dist"
53
+ "dist",
54
+ "setup.md"
54
55
  ],
55
56
  "sideEffects": false,
56
57
  "publishConfig": {
@@ -73,6 +74,5 @@
73
74
  "typescript": "^5.6.3",
74
75
  "vitest": "^2.1.8"
75
76
  },
76
- "packageManager": "pnpm@11.15.1",
77
- "gitHead": "044ae865c8d158ce524ce7c5bcedec440f3a97f9"
77
+ "packageManager": "pnpm@11.15.1"
78
78
  }
package/setup.md ADDED
@@ -0,0 +1,111 @@
1
+ # Set up repo-gates
2
+
3
+ Set up `@fantastic.dev/repo-gates` in the user's repository so developers and
4
+ coding agents can run the same quality checks locally and in CI. Use `init`
5
+ to configure applicable gates, then review and verify the result.
6
+
7
+ Read the [initialization reference](https://github.com/FantasticDevHQ/repo-gates#quickstart)
8
+ before making changes. Follow the repository's own contribution and agent
9
+ instructions. Preserve existing scripts, configuration, and policy choices.
10
+
11
+ ## Inspect the repository
12
+
13
+ - Find the repository root containing `package.json`. Detect the package manager
14
+ from `packageManager` and the lockfile; keep using it throughout setup.
15
+ - Inspect workspace definitions, source directories, existing checks, CI jobs,
16
+ and `repo-gates.config.json` if present. Identify which package owns root tooling.
17
+ - Look for Tailwind v4, `components.json`, ESLint or Oxlint, UI component paths,
18
+ aliases, and app-specific themes. Do not migrate Tailwind or replace a working
19
+ linter just to install repo-gates.
20
+ - Check Node compatibility. The core CLI requires Node 18 or newer. Generated
21
+ ESLint design-system tooling needs Node 20.19+; Oxlint needs Node 20.19.x or
22
+ 22.12+. Match local and CI versions to the tooling actually installed.
23
+
24
+ ## Install and initialize
25
+
26
+ Install the package as a development dependency at the repository root using
27
+ its package manager. For pnpm workspaces, use `pnpm add -Dw` for the install.
28
+
29
+ | Package manager | Install | Initialize | Run checks |
30
+ | --- | --- | --- | --- |
31
+ | npm | `npm install -D @fantastic.dev/repo-gates` | `npx repo-gates init` | `npm run check:all` |
32
+ | pnpm | `pnpm add -D @fantastic.dev/repo-gates` | `pnpm exec repo-gates init` | `pnpm run check:all` |
33
+ | Yarn | `yarn add -D @fantastic.dev/repo-gates` | `yarn exec repo-gates init` | `yarn run check:all` |
34
+ | Bun | `bun add -d @fantastic.dev/repo-gates` | `bunx repo-gates init` | `bun run check:all` |
35
+
36
+ Use the installed CLI. `init` writes scripts and configuration and installs
37
+ applicable UI dependencies. It seeds missing file-size, debt-marker, and
38
+ circular-import baselines. It preserves existing scripts, lint configs, explicit
39
+ policy values, and baselines. Installing the package alone does not initialize it.
40
+
41
+ Keep applicable gates enabled by default. Use `--skip-install` only when dependency
42
+ installation must happen separately, and run the package manager's install command
43
+ before verification. `--no-design-system` and `--no-shadscan` skip setup when the
44
+ user requests it or a documented compatibility constraint requires it; they do
45
+ not remove existing gates. Report any gate you could not configure.
46
+
47
+ If upgrading from `@kellykampen/repo-gates`, follow the
48
+ [migration instructions](https://github.com/FantasticDevHQ/repo-gates#migrating-from-kellykampenrepo-gates),
49
+ including updating imports in existing generated lint configs.
50
+
51
+ ## Review the configuration
52
+
53
+ Review the diff before running the complete suite:
54
+
55
+ - Check `scanRoots`, exclusions, source extensions, and the ordered `gates`
56
+ manifest in `repo-gates.config.json`. Include the intended apps and shared
57
+ packages without scanning generated output or dependencies.
58
+ - Preserve real lint, format, typecheck, and test commands. `init` includes
59
+ recognized existing scripts but does not invent missing checks. Wire missing
60
+ commands only when the project's tools support them. Never add success-only
61
+ placeholder scripts. If an existing `check:all` was preserved, make sure it
62
+ reaches `repo-gates check-all` without calling itself recursively.
63
+ - For Tailwind v4, review `eslint.design-system.config.mjs` or
64
+ `.oxlintrc.design-system.json`. Fresh configs enable all six
65
+ [@shadcn/lint rules](https://github.com/shadcn-ui/lint) as errors. Component
66
+ definitions are exempt from `no-restyle` so they can define their styling;
67
+ the other rules still apply. Verify component scopes, aliases, theme discovery,
68
+ and exclusions for non-v4 workspaces. Existing configs retain their policy.
69
+ See [rule customization](https://github.com/FantasticDevHQ/repo-gates#update-the-rules)
70
+ before editing rule options or overrides.
71
+ - For detected shadcn projects, review `check:shadscan`. The default initial floor
72
+ is 80, a policy choice that can fail on the first run. Fix findings rather than
73
+ lowering an established floor to hide regressions.
74
+ - Keep secret scanning enabled without automatically allowlisting findings.
75
+ `init` deliberately does not seed a secrets allowlist. Secret scanning reads
76
+ Git-tracked files, so newly created, untracked files are not covered yet.
77
+ - If `test:coverage` exists, ensure it emits `json-summary` reports and initialize
78
+ missing coverage floors with `repo-gates check-coverage --init` through the
79
+ installed CLI. Configure docs-coverage surfaces or bundle targets only where
80
+ applicable, using the [policy reference](https://github.com/FantasticDevHQ/repo-gates#how-to-use-it).
81
+
82
+ Do not overwrite baselines, relax rules, or remove failing gates just to get a
83
+ passing result. Distinguish setup errors from existing code findings and report
84
+ remaining work accurately.
85
+
86
+ ## Wire CI and agent instructions
87
+
88
+ Update the existing CI workflow to install development dependencies with the
89
+ repository's lockfile and run its root `check:all` script. Preserve other required
90
+ jobs, credentials, services, and build prerequisites. Keep the command identical
91
+ to the local check entry point; do not make it continue on failure. See the
92
+ [CI examples](https://github.com/FantasticDevHQ/repo-gates/tree/main/examples/github-actions)
93
+ for repository-specific wiring, including PR docs coverage.
94
+
95
+ Add a short instruction to the repository's existing agent guidance telling
96
+ agents to run the appropriate `check:all` command before handing off changes and
97
+ to fix failures without weakening policy. If adding a root `AGENTS.md` for the
98
+ first time, rerun `init` so it can detect and enable the agent-docs gate.
99
+
100
+ ## Verify and hand off
101
+
102
+ Run the root `check:all` command. Investigate configuration or dependency errors,
103
+ then rerun affected checks. If there are existing findings, report the failing
104
+ gates and next steps rather than claiming setup is green. Check that CI invokes
105
+ the same manifest and that the lockfile matches the dependency changes.
106
+
107
+ Summarize what was installed, files changed, gates enabled or omitted and why,
108
+ the exact local/CI command, verification results, and where policy is configured.
109
+ Include package metadata, the lockfile, generated lint configs,
110
+ `repo-gates.config.json`, baseline files, and CI/agent guidance in the proposed
111
+ change. Follow the repository's normal PR workflow for landing it.