@clipboard-health/ai-rules 0.3.3 → 1.1.0

package/README.md

@@ -56,11 +56,11 @@ npm install --save-dev @clipboard-health/ai-rules
 4. Commit the generated files:
 
    ```bash
-   git add AGENTS.md CLAUDE.md
+   git add .
    git commit -m "feat: add AI coding rules"
    ```
 
-5. Bonus: For repo-specific rules, create an `OVERLAY.md` file. The generated files instruct agents to read this file if it exists for additional rules.
+5. Bonus: For repo-specific rules, create an `OVERLAY.md` file. The `sync` script appends its contents in each generated file to load the contents into AI agent context.
 
 ### Updating Rules
 
@@ -74,10 +74,10 @@ npm update @clipboard-health/ai-rules
 npm install
 
 # Review the changes
-git diff AGENTS.md CLAUDE.md
+git diff .
 
 # Commit the updates
-git add AGENTS.md CLAUDE.md
+git add .
 git commit -m "chore: update AI coding rules"
 ```
 

package/backend/AGENTS.md

@@ -170,8 +170,13 @@ Send notifications through [Knock](https://docs.knock.app) using the `@clipboard
 - Avoid magic strings and numbers; define constants.
 - Use camelCase for files and directories (e.g., modules/shiftOffers.ts).
 - When declaring functions, use the `function` keyword, not `const`.
+- Files should read from top to bottom: `export`ed items live on top and the internal functions and methods they call go below them.
 - Prefer data immutability.
 
+# Commit messages
+
+- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
+
 <!-- Source: .ruler/common/errorHandlingAndValidation.md -->
 
 # Error handling and validation
@@ -185,15 +190,6 @@ Send notifications through [Knock](https://docs.knock.app) using the `@clipboard
 - Implement proper error logging and user-friendly error messages.
 - Favor `@clipboard-health/util-ts`'s `Either` type for expected errors instead of `try`/`catch`.
 
-<!-- Source: .ruler/common/keyConventions.md -->
-
-# Key conventions
-
-- You are familiar with the latest features and best practices.
-- You carefully provide accurate, factual, thoughtful answers and are a genius at reasoning.
-- You always write correct, up-to-date, bug-free, fully functional, working, secure, easy-to-read, and efficient code.
-- If there might not be a correct answer or do not know the answer, say so instead of guessing.
-
 <!-- Source: .ruler/common/testing.md -->
 
 # Testing
@@ -223,9 +219,3 @@ Send notifications through [Knock](https://docs.knock.app) using the `@clipboard
 - Leverage `readonly` properties for function parameter immutability.
 - Prefer narrow types whenever possible with `as const` assertions, `typeof`, `instanceof`, `satisfies`, and custom type guards.
 - Implement exhaustiveness checking using `never`.
-
-<!-- Source: .ruler/common/zOverlay.md -->
-
-# Overlay
-
-- If an ./OVERLAY.md file exists, read it for additional rules.

package/backend/CLAUDE.md

@@ -168,8 +168,13 @@ Send notifications through [Knock](https://docs.knock.app) using the `@clipboard
 - Avoid magic strings and numbers; define constants.
 - Use camelCase for files and directories (e.g., modules/shiftOffers.ts).
 - When declaring functions, use the `function` keyword, not `const`.
+- Files should read from top to bottom: `export`ed items live on top and the internal functions and methods they call go below them.
 - Prefer data immutability.
 
+# Commit messages
+
+- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
+
 <!-- Source: .ruler/common/errorHandlingAndValidation.md -->
 
 # Error handling and validation
@@ -183,15 +188,6 @@ Send notifications through [Knock](https://docs.knock.app) using the `@clipboard
 - Implement proper error logging and user-friendly error messages.
 - Favor `@clipboard-health/util-ts`'s `Either` type for expected errors instead of `try`/`catch`.
 
-<!-- Source: .ruler/common/keyConventions.md -->
-
-# Key conventions
-
-- You are familiar with the latest features and best practices.
-- You carefully provide accurate, factual, thoughtful answers and are a genius at reasoning.
-- You always write correct, up-to-date, bug-free, fully functional, working, secure, easy-to-read, and efficient code.
-- If there might not be a correct answer or do not know the answer, say so instead of guessing.
-
 <!-- Source: .ruler/common/testing.md -->
 
 # Testing
@@ -221,9 +217,3 @@ Send notifications through [Knock](https://docs.knock.app) using the `@clipboard
 - Leverage `readonly` properties for function parameter immutability.
 - Prefer narrow types whenever possible with `as const` assertions, `typeof`, `instanceof`, `satisfies`, and custom type guards.
 - Implement exhaustiveness checking using `never`.
-
-<!-- Source: .ruler/common/zOverlay.md -->
-
-# Overlay
-
-- If an ./OVERLAY.md file exists, read it for additional rules.

package/common/AGENTS.md

@@ -12,8 +12,13 @@
 - Avoid magic strings and numbers; define constants.
 - Use camelCase for files and directories (e.g., modules/shiftOffers.ts).
 - When declaring functions, use the `function` keyword, not `const`.
+- Files should read from top to bottom: `export`ed items live on top and the internal functions and methods they call go below them.
 - Prefer data immutability.
 
+# Commit messages
+
+- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
+
 <!-- Source: .ruler/common/errorHandlingAndValidation.md -->
 
 # Error handling and validation
@@ -27,15 +32,6 @@
 - Implement proper error logging and user-friendly error messages.
 - Favor `@clipboard-health/util-ts`'s `Either` type for expected errors instead of `try`/`catch`.
 
-<!-- Source: .ruler/common/keyConventions.md -->
-
-# Key conventions
-
-- You are familiar with the latest features and best practices.
-- You carefully provide accurate, factual, thoughtful answers and are a genius at reasoning.
-- You always write correct, up-to-date, bug-free, fully functional, working, secure, easy-to-read, and efficient code.
-- If there might not be a correct answer or do not know the answer, say so instead of guessing.
-
 <!-- Source: .ruler/common/testing.md -->
 
 # Testing
@@ -65,9 +61,3 @@
 - Leverage `readonly` properties for function parameter immutability.
 - Prefer narrow types whenever possible with `as const` assertions, `typeof`, `instanceof`, `satisfies`, and custom type guards.
 - Implement exhaustiveness checking using `never`.
-
-<!-- Source: .ruler/common/zOverlay.md -->
-
-# Overlay
-
-- If an ./OVERLAY.md file exists, read it for additional rules.

package/common/CLAUDE.md

@@ -10,8 +10,13 @@
 - Avoid magic strings and numbers; define constants.
 - Use camelCase for files and directories (e.g., modules/shiftOffers.ts).
 - When declaring functions, use the `function` keyword, not `const`.
+- Files should read from top to bottom: `export`ed items live on top and the internal functions and methods they call go below them.
 - Prefer data immutability.
 
+# Commit messages
+
+- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
+
 <!-- Source: .ruler/common/errorHandlingAndValidation.md -->
 
 # Error handling and validation
@@ -25,15 +30,6 @@
 - Implement proper error logging and user-friendly error messages.
 - Favor `@clipboard-health/util-ts`'s `Either` type for expected errors instead of `try`/`catch`.
 
-<!-- Source: .ruler/common/keyConventions.md -->
-
-# Key conventions
-
-- You are familiar with the latest features and best practices.
-- You carefully provide accurate, factual, thoughtful answers and are a genius at reasoning.
-- You always write correct, up-to-date, bug-free, fully functional, working, secure, easy-to-read, and efficient code.
-- If there might not be a correct answer or do not know the answer, say so instead of guessing.
-
 <!-- Source: .ruler/common/testing.md -->
 
 # Testing
@@ -63,9 +59,3 @@
 - Leverage `readonly` properties for function parameter immutability.
 - Prefer narrow types whenever possible with `as const` assertions, `typeof`, `instanceof`, `satisfies`, and custom type guards.
 - Implement exhaustiveness checking using `never`.
-
-<!-- Source: .ruler/common/zOverlay.md -->
-
-# Overlay
-
-- If an ./OVERLAY.md file exists, read it for additional rules.

package/frontend/AGENTS.md

@@ -12,8 +12,13 @@
 - Avoid magic strings and numbers; define constants.
 - Use camelCase for files and directories (e.g., modules/shiftOffers.ts).
 - When declaring functions, use the `function` keyword, not `const`.
+- Files should read from top to bottom: `export`ed items live on top and the internal functions and methods they call go below them.
 - Prefer data immutability.
 
+# Commit messages
+
+- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
+
 <!-- Source: .ruler/common/errorHandlingAndValidation.md -->
 
 # Error handling and validation
@@ -27,15 +32,6 @@
 - Implement proper error logging and user-friendly error messages.
 - Favor `@clipboard-health/util-ts`'s `Either` type for expected errors instead of `try`/`catch`.
 
-<!-- Source: .ruler/common/keyConventions.md -->
-
-# Key conventions
-
-- You are familiar with the latest features and best practices.
-- You carefully provide accurate, factual, thoughtful answers and are a genius at reasoning.
-- You always write correct, up-to-date, bug-free, fully functional, working, secure, easy-to-read, and efficient code.
-- If there might not be a correct answer or do not know the answer, say so instead of guessing.
-
 <!-- Source: .ruler/common/testing.md -->
 
 # Testing
@@ -66,12 +62,6 @@
 - Prefer narrow types whenever possible with `as const` assertions, `typeof`, `instanceof`, `satisfies`, and custom type guards.
 - Implement exhaustiveness checking using `never`.
 
-<!-- Source: .ruler/common/zOverlay.md -->
-
-# Overlay
-
-- If an ./OVERLAY.md file exists, read it for additional rules.
-
 <!-- Source: .ruler/frontend/custom-hooks.md -->
 
 # Custom Hook Standards

package/frontend/CLAUDE.md

@@ -10,8 +10,13 @@
 - Avoid magic strings and numbers; define constants.
 - Use camelCase for files and directories (e.g., modules/shiftOffers.ts).
 - When declaring functions, use the `function` keyword, not `const`.
+- Files should read from top to bottom: `export`ed items live on top and the internal functions and methods they call go below them.
 - Prefer data immutability.
 
+# Commit messages
+
+- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
+
 <!-- Source: .ruler/common/errorHandlingAndValidation.md -->
 
 # Error handling and validation
@@ -25,15 +30,6 @@
 - Implement proper error logging and user-friendly error messages.
 - Favor `@clipboard-health/util-ts`'s `Either` type for expected errors instead of `try`/`catch`.
 
-<!-- Source: .ruler/common/keyConventions.md -->
-
-# Key conventions
-
-- You are familiar with the latest features and best practices.
-- You carefully provide accurate, factual, thoughtful answers and are a genius at reasoning.
-- You always write correct, up-to-date, bug-free, fully functional, working, secure, easy-to-read, and efficient code.
-- If there might not be a correct answer or do not know the answer, say so instead of guessing.
-
 <!-- Source: .ruler/common/testing.md -->
 
 # Testing
@@ -64,12 +60,6 @@
 - Prefer narrow types whenever possible with `as const` assertions, `typeof`, `instanceof`, `satisfies`, and custom type guards.
 - Implement exhaustiveness checking using `never`.
 
-<!-- Source: .ruler/common/zOverlay.md -->
-
-# Overlay
-
-- If an ./OVERLAY.md file exists, read it for additional rules.
-
 <!-- Source: .ruler/frontend/custom-hooks.md -->
 
 # Custom Hook Standards

package/fullstack/AGENTS.md

@@ -170,8 +170,13 @@ Send notifications through [Knock](https://docs.knock.app) using the `@clipboard
 - Avoid magic strings and numbers; define constants.
 - Use camelCase for files and directories (e.g., modules/shiftOffers.ts).
 - When declaring functions, use the `function` keyword, not `const`.
+- Files should read from top to bottom: `export`ed items live on top and the internal functions and methods they call go below them.
 - Prefer data immutability.
 
+# Commit messages
+
+- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
+
 <!-- Source: .ruler/common/errorHandlingAndValidation.md -->
 
 # Error handling and validation
@@ -185,15 +190,6 @@ Send notifications through [Knock](https://docs.knock.app) using the `@clipboard
 - Implement proper error logging and user-friendly error messages.
 - Favor `@clipboard-health/util-ts`'s `Either` type for expected errors instead of `try`/`catch`.
 
-<!-- Source: .ruler/common/keyConventions.md -->
-
-# Key conventions
-
-- You are familiar with the latest features and best practices.
-- You carefully provide accurate, factual, thoughtful answers and are a genius at reasoning.
-- You always write correct, up-to-date, bug-free, fully functional, working, secure, easy-to-read, and efficient code.
-- If there might not be a correct answer or do not know the answer, say so instead of guessing.
-
 <!-- Source: .ruler/common/testing.md -->
 
 # Testing
@@ -224,12 +220,6 @@ Send notifications through [Knock](https://docs.knock.app) using the `@clipboard
 - Prefer narrow types whenever possible with `as const` assertions, `typeof`, `instanceof`, `satisfies`, and custom type guards.
 - Implement exhaustiveness checking using `never`.
 
-<!-- Source: .ruler/common/zOverlay.md -->
-
-# Overlay
-
-- If an ./OVERLAY.md file exists, read it for additional rules.
-
 <!-- Source: .ruler/frontend/custom-hooks.md -->
 
 # Custom Hook Standards

package/fullstack/CLAUDE.md

@@ -168,8 +168,13 @@ Send notifications through [Knock](https://docs.knock.app) using the `@clipboard
 - Avoid magic strings and numbers; define constants.
 - Use camelCase for files and directories (e.g., modules/shiftOffers.ts).
 - When declaring functions, use the `function` keyword, not `const`.
+- Files should read from top to bottom: `export`ed items live on top and the internal functions and methods they call go below them.
 - Prefer data immutability.
 
+# Commit messages
+
+- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
+
 <!-- Source: .ruler/common/errorHandlingAndValidation.md -->
 
 # Error handling and validation
@@ -183,15 +188,6 @@ Send notifications through [Knock](https://docs.knock.app) using the `@clipboard
 - Implement proper error logging and user-friendly error messages.
 - Favor `@clipboard-health/util-ts`'s `Either` type for expected errors instead of `try`/`catch`.
 
-<!-- Source: .ruler/common/keyConventions.md -->
-
-# Key conventions
-
-- You are familiar with the latest features and best practices.
-- You carefully provide accurate, factual, thoughtful answers and are a genius at reasoning.
-- You always write correct, up-to-date, bug-free, fully functional, working, secure, easy-to-read, and efficient code.
-- If there might not be a correct answer or do not know the answer, say so instead of guessing.
-
 <!-- Source: .ruler/common/testing.md -->
 
 # Testing
@@ -222,12 +218,6 @@ Send notifications through [Knock](https://docs.knock.app) using the `@clipboard
 - Prefer narrow types whenever possible with `as const` assertions, `typeof`, `instanceof`, `satisfies`, and custom type guards.
 - Implement exhaustiveness checking using `never`.
 
-<!-- Source: .ruler/common/zOverlay.md -->
-
-# Overlay
-
-- If an ./OVERLAY.md file exists, read it for additional rules.
-
 <!-- Source: .ruler/frontend/custom-hooks.md -->
 
 # Custom Hook Standards

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clipboard-health/ai-rules",
   "description": "Pre-built AI agent rules for consistent coding standards.",
-  "version": "0.3.3",
+  "version": "1.1.0",
   "bugs": "https://github.com/ClipboardHealth/core-utils/issues",
   "devDependencies": {
     "@intellectronica/ruler": "0.3.10"

package/scripts/constants.js

@@ -1,11 +1,14 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PROFILES = exports.PATHS = void 0;
-const node_path_1 = require("node:path");
-const packageRoot = (0, node_path_1.join)(__dirname, "..");
+const node_path_1 = __importDefault(require("node:path"));
+const packageRoot = node_path_1.default.join(__dirname, "..");
 exports.PATHS = {
     packageRoot,
-    outputDirectory: (0, node_path_1.join)(packageRoot, "..", "..", "dist", "packages", "ai-rules"),
+    outputDirectory: node_path_1.default.join(packageRoot, "..", "..", "dist", "packages", "ai-rules"),
 };
 exports.PROFILES = {
     frontend: ["common", "frontend"],

package/scripts/sync.js

@@ -1,15 +1,36 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-/* eslint-disable unicorn/no-process-exit */
-/* eslint-disable n/no-process-exit */
+/* eslint-disable unicorn/no-process-exit, n/no-process-exit */
+// eslint-disable-next-line n/no-unsupported-features/node-builtins
 const promises_1 = require("node:fs/promises");
-const node_path_1 = require("node:path");
+const node_path_1 = __importDefault(require("node:path"));
 const constants_1 = require("./constants");
 const toErrorMessage_1 = require("./toErrorMessage");
 const PATHS = {
-    projectRoot: (0, node_path_1.join)(__dirname, "../../../.."),
-    rules: (0, node_path_1.join)(__dirname, ".."),
+    projectRoot: node_path_1.default.join(__dirname, "../../../.."),
+    rules: node_path_1.default.join(__dirname, ".."),
 };
+async function sync() {
+    try {
+        const profile = getProfileFromArguments();
+        // Force copy files; rely on `git` if it overwrites files.
+        await (0, promises_1.cp)(node_path_1.default.join(PATHS.rules, profile), PATHS.projectRoot, { force: true, recursive: true });
+        console.log(`✅ @clipboard-health/ai-rules synced ${profile}`);
+        // Append OVERLAY.md content if it exists
+        await appendOverlayToFiles({
+            filesToUpdate: ["CLAUDE.md", "AGENTS.md"],
+            projectRoot: PATHS.projectRoot,
+        });
+    }
+    catch (error) {
+        // Log error but exit gracefully to avoid breaking installs
+        console.error(`⚠️ @clipboard-health/ai-rules sync failed: ${(0, toErrorMessage_1.toErrorMessage)(error)}`);
+        process.exit(0);
+    }
+}
 function getProfileFromArguments() {
     const profile = process.argv[2];
     if (!profile || !(profile in constants_1.PROFILES)) {
@@ -20,20 +41,39 @@ function getProfileFromArguments() {
     }
     return profile;
 }
-async function sync() {
+/**
+ * Appends OVERLAY.md content to specified files if OVERLAY.md exists.
+ */
+async function appendOverlayToFiles(params) {
+    const { filesToUpdate, projectRoot } = params;
+    const overlayPath = node_path_1.default.join(projectRoot, "OVERLAY.md");
+    const overlayContent = await readOverlayContent(overlayPath);
+    if (!overlayContent) {
+        // OVERLAY.md doesn't exist or can't be read, nothing to append
+        return;
+    }
+    // Append to each file
+    await Promise.all(filesToUpdate.map(async (file) => {
+        const filePath = node_path_1.default.join(projectRoot, file);
+        try {
+            const currentContent = await (0, promises_1.readFile)(filePath, "utf8");
+            const updatedContent = `${currentContent}\n<!-- Source: ./OVERLAY.md -->\n\n${overlayContent}`;
+            await (0, promises_1.writeFile)(filePath, updatedContent, "utf8");
+        }
+        catch (error) {
+            console.warn(`⚠️ Could not append overlay to ${file}: ${(0, toErrorMessage_1.toErrorMessage)(error)}`);
+        }
+    }));
+    console.log(`📎 Appended OVERLAY.md to ${filesToUpdate.join(", ")}`);
+}
+async function readOverlayContent(overlayPath) {
     try {
-        const profile = getProfileFromArguments();
-        // Force copy files; rely on `git` if it overwrites files.
-        await (0, promises_1.cp)((0, node_path_1.join)(PATHS.rules, profile), PATHS.projectRoot, { recursive: true, force: true });
-        console.log(`✅ @clipboard-health/ai-rules synced ${profile}`);
+        return await (0, promises_1.readFile)(overlayPath, "utf8");
     }
-    catch (error) {
-        // Log error but exit gracefully to avoid breaking installs
-        console.error(`⚠️ @clipboard-health/ai-rules sync failed: ${(0, toErrorMessage_1.toErrorMessage)(error)}`);
-        process.exit(0);
+    catch {
+        return undefined;
     }
 }
 // eslint-disable-next-line unicorn/prefer-top-level-await
 void sync();
-/* eslint-enable n/no-process-exit */
-/* eslint-enable unicorn/no-process-exit */
+/* eslint-enable unicorn/no-process-exit, n/no-process-exit */