@clipboard-health/ai-rules 1.0.0 → 1.1.1

package/README.md

@@ -60,7 +60,7 @@ npm install --save-dev @clipboard-health/ai-rules
    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
 

package/backend/AGENTS.md

@@ -170,8 +170,12 @@ 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.
-- Use Conventional Commits 1.0 for commit messages.
+
+# Commit messages
+
+- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
 
 <!-- Source: .ruler/common/errorHandlingAndValidation.md -->
 
@@ -215,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,12 @@ 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.
-- Use Conventional Commits 1.0 for commit messages.
+
+# Commit messages
+
+- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
 
 <!-- Source: .ruler/common/errorHandlingAndValidation.md -->
 
@@ -213,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,12 @@
 - 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.
-- Use Conventional Commits 1.0 for commit messages.
+
+# Commit messages
+
+- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
 
 <!-- Source: .ruler/common/errorHandlingAndValidation.md -->
 
@@ -57,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,12 @@
 - 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.
-- Use Conventional Commits 1.0 for commit messages.
+
+# Commit messages
+
+- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
 
 <!-- Source: .ruler/common/errorHandlingAndValidation.md -->
 
@@ -55,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,12 @@
 - 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.
-- Use Conventional Commits 1.0 for commit messages.
+
+# Commit messages
+
+- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
 
 <!-- Source: .ruler/common/errorHandlingAndValidation.md -->
 
@@ -58,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,12 @@
 - 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.
-- Use Conventional Commits 1.0 for commit messages.
+
+# Commit messages
+
+- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
 
 <!-- Source: .ruler/common/errorHandlingAndValidation.md -->
 
@@ -56,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,12 @@ 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.
-- Use Conventional Commits 1.0 for commit messages.
+
+# Commit messages
+
+- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
 
 <!-- Source: .ruler/common/errorHandlingAndValidation.md -->
 
@@ -216,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,12 @@ 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.
-- Use Conventional Commits 1.0 for commit messages.
+
+# Commit messages
+
+- Follow the Conventional Commits 1.0 spec for commit messages and in pull request titles.
 
 <!-- Source: .ruler/common/errorHandlingAndValidation.md -->
 
@@ -214,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": "1.0.0",
+  "version": "1.1.1",
   "bugs": "https://github.com/ClipboardHealth/core-utils/issues",
   "devDependencies": {
     "@intellectronica/ruler": "0.3.10"

package/scripts/sync.js

@@ -4,7 +4,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 /* 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 = __importDefault(require("node:path"));
 const constants_1 = require("./constants");
@@ -13,6 +12,24 @@ const PATHS = {
     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)) {
@@ -23,17 +40,37 @@ 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)(node_path_1.default.join(PATHS.rules, profile), PATHS.projectRoot, { force: true, recursive: 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