chore: enhance project for AI-assisted development

.coderabbit.yaml

@@ -1,11 +1,42 @@
 # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
 ---
 reviews:
+  tone_instructions: "Be direct and concise. Focus on correctness of async/await patterns, error handling, and GraphQL API usage."
+
   path_instructions:
-    - path: src/**/*.js
+    - path: src/api.js
       instructions: |
-        Review JavaScript code for:
-        - Proper async/await and Promise handling
-        - Error handling and graceful failures
-        - GitHub API usage patterns
-        - SVG generation best practices
+        GraphQL client singleton. Review for:
+        - Token validation before API calls
+        - Error handling patterns
+        - Singleton pattern correctness
+
+    - path: src/cli.js
+      instructions: |
+        CLI entrypoint. Review for:
+        - Argument parsing correctness
+        - Error messaging clarity
+        - User experience
+
+    - path: src/{contribs,repo,org}.js
+      instructions: |
+        Statistics collection modules. Review for:
+        - GraphQL query correctness
+        - Data transformation accuracy
+        - Error handling for API failures
+
+    - path: .github/workflows/*.yml
+      instructions: |
+        Review workflows for:
+
+        Security:
+        - Proper secret handling via ${{ secrets.* }}
+        - SSH signing configured correctly
+
+        Efficiency:
+        - Concurrency groups prevent duplicate runs
+        - Path filters for relevant changes
+
+        Correctness:
+        - Proper trigger conditions
+        - Fetch depth appropriate for git operations

.cursor/agents/code-reviewer.md

@@ -0,0 +1,32 @@
+---
+name: code-reviewer
+description: Pre-commit code review checklist
+---
+
+# Pre-Commit Code Review
+
+Review the code changes:
+
+## Code Quality
+
+- [ ] All async functions use `await` (no floating promises)
+- [ ] GraphQL queries are syntactically correct
+- [ ] Error handling wraps all API calls with try/catch
+- [ ] No hardcoded tokens, secrets, or credentials in code
+- [ ] ESLint passes: `npm run lint`
+
+## API Client Usage
+
+- [ ] Uses `require('./api')` singleton for GraphQL client
+- [ ] Token comes from environment variable only
+- [ ] Error messages are clear and actionable
+
+## Testing
+
+Test manually:
+
+```bash
+npm run contribs
+npm run repo <repo-name>
+npm run org <org-name>
+```

.cursor/agents/docs-writer.md

@@ -0,0 +1,29 @@
+---
+name: docs-writer
+description: Documentation update assistant
+---
+
+# Documentation Updates
+
+When updating documentation:
+
+## README.md Updates
+
+- Update version examples if API changes
+- Update token scope requirements if queries change
+- Keep examples between `<!--START OF STATS-->` and `<!--END OF STATS-->` unchanged (auto-updated by workflow)
+- Keep examples between `<!--START OF REPO-->` and `<!--END OF REPO-->` unchanged (auto-updated by workflow)
+- Verify all code examples are tested
+
+## CONTRIBUTING.md Updates
+
+- Keep development setup instructions current
+- Update Cursor IDE section if agents/commands/skills change
+- Verify all commands work
+
+## Code Comments
+
+- Focus on "why" not "what"
+- Document GraphQL query structure
+- Explain non-obvious error handling
+- Document token scope requirements for API calls

.cursor/commands/lint.md

@@ -0,0 +1,12 @@
+---
+name: lint
+description: Run ESLint on source files
+---
+
+```bash
+npm run lint
+```
+
+Runs ESLint with the configuration in `eslint.config.mjs`.
+
+Checks all JavaScript files in the `src/` directory for code quality issues.

.cursor/commands/test-contribs.md

@@ -0,0 +1,16 @@
+---
+name: test-contribs
+description: Test the contribs command locally (requires GITHUB_TOKEN)
+---
+
+Test the user contributions statistics command:
+
+```bash
+npm run contribs
+```
+
+**Prerequisites:**
+- `GITHUB_TOKEN` environment variable must be set
+- Token requires scopes: `repo`, `read:packages`, `read:user`, `read:discussion`
+
+The command will print your GitHub user statistics as JSON.

.cursor/commands/test-org.md

@@ -0,0 +1,18 @@
+---
+name: test-org
+description: Test the org command locally (requires GITHUB_TOKEN)
+---
+
+Test the organization statistics command:
+
+```bash
+npm run org <org-name>
+```
+
+Replace `<org-name>` with an organization name you have access to.
+
+**Prerequisites:**
+- `GITHUB_TOKEN` environment variable must be set
+- Token requires scopes: `read:org` (or `admin:org` for admin-level stats like 2FA and pending members)
+
+The command will print organization statistics as JSON.

.cursor/commands/test-repo.md

@@ -0,0 +1,18 @@
+---
+name: test-repo
+description: Test the repo command locally (requires GITHUB_TOKEN)
+---
+
+Test the repository statistics command:
+
+```bash
+npm run repo <repo-name>
+```
+
+Replace `<repo-name>` with the name of one of your repositories (e.g., `aioswitcher`).
+
+**Prerequisites:**
+- `GITHUB_TOKEN` environment variable must be set
+- Token requires scopes: `repo`, `read:packages`
+
+The command will print repository statistics as JSON.

.cursor/rules/project-rules.mdc

@@ -0,0 +1,62 @@
+---
+description: github-viewer-stats project conventions and development guidelines
+alwaysApply: true
+---
+
+# github-viewer-stats Project Rules
+
+## Project Overview
+
+A lightweight Node.js CLI tool and library for collecting GitHub statistics using the GraphQL API.
+
+## Coding Conventions
+
+### JavaScript Style
+- Use CommonJS modules (`module.exports`, `require`)
+- Prefer `async`/`await` over raw Promises
+- Use template literals for string interpolation
+- Follow existing indentation (2 spaces, per `.editorconfig`)
+
+### Error Handling
+- Validate `GITHUB_TOKEN` environment variable before API calls
+- Provide clear, actionable error messages
+- Handle GraphQL API errors gracefully
+
+### API Usage
+- Use `@octokit/graphql` for GitHub GraphQL API calls
+- Singleton pattern for API client (see `src/api.js`)
+- Token authentication via `GITHUB_TOKEN` environment variable
+
+## Architecture Constraints
+
+### File Organization
+- `src/index.js` - Main module exports
+- `src/api.js` - GraphQL client factory
+- `src/cli.js` - CLI entrypoint
+- `src/contribs.js` - User contribution stats
+- `src/repo.js` - Repository stats
+- `src/org.js` - Organization stats
+
+### Dependencies
+- Keep dependencies minimal
+- Only `@octokit/graphql` for runtime
+- Dev dependencies for linting only
+
+## Development Tools
+
+### Linting
+```bash
+npm run lint
+```
+
+ESLint is configured via `eslint.config.mjs` with recommended rules for Node.js/CommonJS.
+
+### Testing Locally
+Requires a `GITHUB_TOKEN` environment variable with scopes: `repo`, `read:packages`, `read:user`, `read:discussion`, `read:org` (or `admin:org` for full org stats).
+
+Test commands:
+```bash
+npm run contribs
+npm run repo <repo-name>
+npm run org <org-name>
+```

.cursor/skills/add-stats-module/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: add-stats-module
+description: Guide for adding new GitHub statistics collection modules
+---
+
+# Adding a New Statistics Module
+
+Follow these steps to add a new statistics collection module:
+
+## 1. Create the Module File
+
+Create `src/new-module.js`:
+
+```javascript
+const { graphql } = require('./api');
+
+module.exports = async function(arg) {
+  // Validate argument if needed
+  if (!arg) {
+    throw new Error('Argument required');
+  }
+
+  // GraphQL query
+  const query = `
+    query($arg: String!) {
+      # Your GraphQL query here
+    }
+  `;
+
+  try {
+    const result = await graphql(query, { arg });
+
+    // Transform and return data
+    return {
+      // Your data structure
+    };
+  } catch (error) {
+    throw new Error(`Failed to fetch stats: ${error.message}`);
+  }
+};
+```
+
+## 2. Export from Index
+
+Add to `src/index.js`:
+
+```javascript
+exports.newModule = require('./new-module');
+```
+
+## 3. Add CLI Command
+
+Update `src/cli.js` to add the command:
+
+```javascript
+case 'newmodule':
+  return require('./new-module')(process.argv[3]);
+```
+
+## 4. Add npm Script
+
+Update `package.json` scripts section:
+
+```json
+"newmodule": "run(){ node -e \"async function run() { console.log(JSON.stringify(await require('./src/new-module')('$1'), null, 2)) } run()\"; }; run"
+```
+
+## 5. Add Test Command
+
+Create `.cursor/commands/test-newmodule.md`:
+
+```markdown
+---
+name: test-newmodule
+description: Test the new module command
+---
+
+Test the new module command:
+
+\`\`\`bash
+npm run newmodule <arg>
+\`\`\`
+
+**Prerequisites:**
+- `GITHUB_TOKEN` environment variable must be set
+- Token requires appropriate scopes
+
+The command will print statistics as JSON.
+```
+
+## 6. Update Documentation
+
+Update README.md with usage example:
+
+```markdown
+\`\`\`shell
+npx github-viewer-stats newmodule <arg>
+\`\`\`
+
+\`\`\`json
+{
+  "example": "output"
+}
+\`\`\`
+```
+
+## GraphQL Query Tips
+
+- Use the GitHub GraphQL Explorer: https://docs.github.com/en/graphql/overview/explorer
+- Test queries before implementing
+- Handle pagination if needed
+- Include error handling for rate limits