From d8268097fae4db5312fac31918a967a50b9928aa Mon Sep 17 00:00:00 2001 From: Thomas Stang Date: Wed, 25 Feb 2026 12:57:00 -0600 Subject: [PATCH] chore: add agent instruction files for all providers Generated by oat-agent-instructions-apply from analysis artifact. Files: 6 created, 0 updated. - AGENTS.md: canonical root instructions (tech stack, commands, conventions) - website/AGENTS.md: scoped instructions for Docusaurus documentation site - CLAUDE.md: @AGENTS.md import shim for Claude Code - .cursor/rules/project.mdc: always-on Cursor project conventions - .cursor/rules/testing.mdc: glob-scoped Jest testing conventions (Cursor) - .claude/rules/testing.md: path-scoped Jest testing conventions (Claude) --- .claude/rules/testing.md | 31 ++++++++++++++ .cursor/rules/project.mdc | 19 +++++++++ .cursor/rules/testing.mdc | 33 +++++++++++++++ AGENTS.md | 88 +++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + website/AGENTS.md | 32 ++++++++++++++ 6 files changed, 204 insertions(+) create mode 100644 .claude/rules/testing.md create mode 100644 .cursor/rules/project.mdc create mode 100644 .cursor/rules/testing.mdc create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 website/AGENTS.md diff --git a/.claude/rules/testing.md b/.claude/rules/testing.md new file mode 100644 index 0000000..5107896 --- /dev/null +++ b/.claude/rules/testing.md @@ -0,0 +1,31 @@ +--- +paths: + - "**/*.test.js" +--- + +# Testing Conventions + +Jest test files for Clay CLI. Tests are co-located with source files (`foo.test.js` next to `foo.js`). + +## Setup + +Global test setup lives in `setup-jest.js` at the repo root. It: +- Mocks `home-config` globally (used by config commands) +- Sets up `jest-fetch-mock` as the global `fetch` (replaces `isomorphic-fetch`) + +Do NOT re-mock `home-config` or `isomorphic-fetch` in individual test files — the global setup handles this. + +## Conventions + +- Use `jest-fetch-mock` for HTTP request mocking — `fetch` is globally available +- Use `mock-fs` for filesystem mocking — call `mockFs.restore()` in `afterEach` +- Use `jest-mock-console` for console output assertions +- Use `jest.fn()` and `jest.mock()` for module mocking — `automock` is disabled +- Prefer `describe`/`it` blocks for test organization +- Each test file should require its module under test with a fresh `require` + +## Patterns + +- Mock setup in `beforeEach`, cleanup in `afterEach` +- Assert on function return values and side effects, not implementation details +- Test both success and error paths for async operations diff --git a/.cursor/rules/project.mdc b/.cursor/rules/project.mdc new file mode 100644 index 0000000..a672bb8 --- /dev/null +++ b/.cursor/rules/project.mdc @@ -0,0 +1,19 @@ +--- +description: "Clay CLI project conventions — CommonJS Node.js CLI tool with Jest testing" +alwaysApply: true +--- + +# Clay CLI Project Conventions + +This is a Node.js CLI tool using CommonJS modules. See `AGENTS.md` at the repository root for full project instructions. + +## Quick Reference + +- **Modules:** CommonJS only (`require`/`module.exports`), never ESM +- **Style:** 2-space indent, single quotes, semicolons, `'use strict'` in every file +- **Test:** `npm test` (lint + Jest), `npm run watch` for watch mode +- **Lint:** `npm run lint` (ESLint) +- **Tests:** Co-located `*.test.js` files next to source +- **HTTP:** `isomorphic-fetch` (mocked via `jest-fetch-mock` in tests) +- **Streams:** Highland.js for data processing pipelines +- **Complexity:** Max cyclomatic complexity 8, max nesting depth 4, max params 4 diff --git a/.cursor/rules/testing.mdc b/.cursor/rules/testing.mdc new file mode 100644 index 0000000..7dc0e2b --- /dev/null +++ b/.cursor/rules/testing.mdc @@ -0,0 +1,33 @@ +--- +description: "Jest testing conventions for Clay CLI" +alwaysApply: false +globs: + - "**/*.test.js" +--- + +# Testing Conventions + +Jest test files for Clay CLI. Tests are co-located with source files (`foo.test.js` next to `foo.js`). + +## Setup + +Global test setup lives in `setup-jest.js` at the repo root. It: +- Mocks `home-config` globally (used by config commands) +- Sets up `jest-fetch-mock` as the global `fetch` (replaces `isomorphic-fetch`) + +Do NOT re-mock `home-config` or `isomorphic-fetch` in individual test files — the global setup handles this. + +## Conventions + +- Use `jest-fetch-mock` for HTTP request mocking — `fetch` is globally available +- Use `mock-fs` for filesystem mocking — call `mockFs.restore()` in `afterEach` +- Use `jest-mock-console` for console output assertions +- Use `jest.fn()` and `jest.mock()` for module mocking — `automock` is disabled +- Prefer `describe`/`it` blocks for test organization +- Each test file should require its module under test with a fresh `require` + +## Patterns + +- Mock setup in `beforeEach`, cleanup in `afterEach` +- Assert on function return values and side effects, not implementation details +- Test both success and error paths for async operations diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d591ffe --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,88 @@ +# Clay CLI + +A command-line interface for Clay CMS. Provides commands for importing, exporting, compiling, linting, configuring, and packing Clay components. Published as an npm package (`claycli`) with both CLI (`clay`) and programmatic API entry points. + +## Non-Negotiables + +- Never commit secrets, API keys, or `.npmrc` credentials +- Do not modify `.circleci/` config without approval +- Do not modify `package.json` publish/release scripts without approval +- All code must use `'use strict';` at the top of every file +- CommonJS modules only (`require`/`module.exports`) — do NOT use ESM (`import`/`export`) + +## Development Commands + +### Essential Commands +- `npm install` - Install dependencies +- `npm test` - Run lint + all tests (Jest) +- `npm run lint` - Lint code (ESLint) +- `npm run watch` - Run tests in watch mode (Jest --watch) + +### Single Test File +- `npx jest path/to/file.test.js` - Run a specific test file + +### Release +- `npm run release` - Release via CircleCI script (do not run locally without approval) + +## Architecture Overview + +The project has two entry points: a CLI (`cli/index.js`) invoked via `clay ` and a programmatic API (`index.js`) that exports command modules. + +### Key Directories +- `cli/` - Yargs-based CLI entry points; each command is a yargs module +- `lib/` - Core library code shared between CLI and programmatic API +- `lib/cmd/` - Command implementations (compile, config, export, import, lint, pack) +- `lib/cmd/compile/` - Template/CSS/JS compilation pipeline using Browserify, Webpack 5, Gulp 4, Babel +- `lib/cmd/pack/` - Webpack-based component packing +- `lib/reporters/` - Output formatters +- `lib/gulp-plugins/` - Custom Gulp plugins +- `website/` - Docusaurus documentation site (separate build system, see `website/AGENTS.md`) +- `docs/` - Documentation source files consumed by the website + +### Technology Stack +- **Runtime:** Node.js (CommonJS modules, tested on Node 10/12/14) +- **CLI framework:** yargs +- **Build tooling:** Browserify, Webpack 5, Gulp 4, Babel +- **Testing:** Jest 24 with jest-fetch-mock, mock-fs, jest-mock-console +- **Linting:** ESLint 7 with @babel/eslint-parser +- **CI:** CircleCI (test on Node 10/12/14, deploy docs, publish to npm) + +## Code Conventions + +### Style +- 2-space indentation +- Single quotes (`'avoid-escape'`) +- Semicolons required +- `1tbs` brace style (one true brace style) +- `vars-on-top` — declare variables at top of scope +- `newline-after-var` — blank line after variable declarations +- Named functions: no space before parens; anonymous functions: space before parens + +### Patterns +- CommonJS `require`/`module.exports` throughout (NOT ESM) +- Lodash for utilities (babel-plugin-lodash optimizes imports) +- `isomorphic-fetch` for HTTP requests (mocked in tests via `jest-fetch-mock`) +- Highland.js streams for data processing pipelines +- Promises via `kew` library in some modules + +### Complexity Limits (enforced by ESLint) +- Max cyclomatic complexity: 8 +- Max nesting depth: 4 +- Max function parameters: 4 +- Max nested callbacks: 4 + +## Testing + +- Tests are co-located with source: `foo.js` has `foo.test.js` in the same directory +- Global test setup in `setup-jest.js`: mocks `home-config` and sets up `jest-fetch-mock` globally +- Use `jest-fetch-mock` for HTTP request mocking (globally available as `fetch`) +- Use `mock-fs` for filesystem mocking +- Use `jest-mock-console` for console output assertions +- Coverage is collected automatically (configured in package.json) + +## Definition of Done + +- [ ] Tests pass (`npm test`) +- [ ] Lint clean (`npm run lint`) +- [ ] No debug logs or temporary code left in source +- [ ] New features include co-located test files diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/website/AGENTS.md b/website/AGENTS.md new file mode 100644 index 0000000..627c8a8 --- /dev/null +++ b/website/AGENTS.md @@ -0,0 +1,32 @@ +# Clay CLI Documentation Site + +Docusaurus 1.x documentation site for Clay CLI. Separate from the main CLI project — has its own package.json, build system, and deployment. + +## Commands + +- `npm install` - Install website dependencies (run from `website/` directory) +- `npm start` - Start local dev server (`docusaurus-start`) +- `npm run build` - Build static site (`docusaurus-build`) +- `npm run deploy` - Deploy to GitHub Pages (`gh-pages -d build/claycli`) + +## Architecture + +- `siteConfig.js` - Docusaurus site configuration +- `sidebars.json` - Documentation sidebar structure +- `../docs/` - Markdown source files (live in parent `docs/` directory) + +### Technology Stack +- **Framework:** Docusaurus 1.x +- **Deployment:** GitHub Pages via `gh-pages` +- **CI:** Deployed by CircleCI on master branch after tests pass + +## Conventions + +- Documentation source files live in `../docs/`, not in this directory +- Do not modify deployment scripts without approval +- Site builds are triggered by CircleCI, not run locally in production + +## Definition of Done + +- [ ] Site builds without errors (`npm run build`) +- [ ] Links and sidebar structure are valid