@genesislcap/genx 15.23.0 → 15.23.1-agent-rules.1

package/README.md

@@ -26,6 +26,30 @@ To enable this module in your application, follow the steps below.
 
 ## [API Docs](./docs/api/index.md)
 
+## Agent rules
+
+`genx agent-rules` installs the shared AI agent rules that ship with this package
+([`agent-rules/`](./agent-rules)) into a consumer project, and wires them into whichever assistants
+that project uses.
+
+```bash
+npx genx agent-rules                                  # install and wire up detected assistants
+npx genx agent-rules --tools claude,cursor,gemini     # wire up specific assistants
+npx genx agent-rules --check                          # CI: fail when installed rules are stale
+```
+
+The rule markdown is copied to `docs/agent-rules/` and referenced from a managed block in
+`CLAUDE.md`, `GEMINI.md`, or `AGENTS.md`, and from a generated `.cursor/rules/<rule>.mdc` for
+Cursor. Content outside the managed block is never touched. Installed copies are managed — re-run
+the command after `genx upgrade` to pick up rule changes, and propose edits in
+[foundation-ui](https://github.com/genesislcap/foundation-ui) rather than locally.
+
+Currently shipped:
+
+| Rule | Purpose |
+| --- | --- |
+| `report-upstream-bug.md` | File a bug in `genesislcap/foundation-ui` — with the human's confirmation — instead of quietly working around it in the consumer project. |
+
 ## Event type codegen
 
 When `eventTypes.enabled` is set in `genx.config.*` or `package.json` (`genx` / `genesis` keys), `genx build` and `genx generate event-types` emit typed `EventDetailsMap` from Kotlin handler DTOs and generated table DAOs. See [@genesislcap/event-type-codegen](../event-type-codegen/README.md) for configuration, limitations, and migration.

package/agent-rules/manifest.json

@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "targetDir": "docs/agent-rules",
+  "rules": [
+    {
+      "file": "report-upstream-bug.md",
+      "name": "report-upstream-bug",
+      "title": "Report Foundation UI bugs upstream",
+      "description": "File a bug upstream in genesislcap/foundation-ui instead of working around it locally. Use whenever a defect is traced into a @genesislcap/* package - a stack frame in node_modules/@genesislcap, or behaviour contradicting the package's docs or types - or before writing any monkey-patch, patch-package entry, vendored copy, version pin, or cast that exists to route around upstream behaviour.",
+      "cursorDescription": "- When a bug is traced into a @genesislcap package, When considering a workaround for upstream behaviour, When patching node_modules or pinning a @genesislcap version"
+    }
+  ]
+}

package/agent-rules/report-upstream-bug.md

@@ -0,0 +1,249 @@
+<!-- Managed by `genx agent-rules` (@genesislcap/genx). Do not edit this copy — it is overwritten on every run. Propose changes in genesislcap/foundation-ui. -->
+
+# Report Foundation UI bugs upstream (don't silently work around them)
+
+> **Purpose**: When a bug in this project turns out to live inside a `@genesislcap/*` package,
+> the fix belongs in [`genesislcap/foundation-ui`](https://github.com/genesislcap/foundation-ui),
+> not in a local patch. A workaround that is never reported keeps every other consumer project
+> broken and quietly becomes permanent. This rule makes "raise it upstream" the default path and
+> a local workaround the deliberate, approved, clearly-marked exception.
+
+## When this rule applies
+
+Apply it as soon as any of these is true:
+
+- A stack frame, breakpoint, or console error points into `node_modules/@genesislcap/**`.
+- The behaviour of a `@genesislcap/*` package contradicts its own docs, types, JSDoc, or
+  README — including a `CustomEvent<unknown>` where a typed detail is documented.
+- You are about to write, or have caught yourself considering, any of these:
+  - a monkey-patch, prototype override, or `patch-package` entry against a `@genesislcap/*` package;
+  - a copy of an upstream component/function into this repo so a few lines can be changed;
+  - `as any` / `@ts-expect-error` / `// eslint-disable` purely to route around a wrong upstream type;
+  - a CSS override fighting an upstream style (`!important` into a shadow part, etc.);
+  - pinning or downgrading a `@genesislcap/*` version to dodge a regression;
+  - a `setTimeout`, extra re-render, retry, or "nudge" that exists only to compensate for
+    upstream timing.
+
+It does **not** apply when the cause is on this side: wrong usage of a documented API, a version
+mismatch between `@genesislcap/*` packages, missing peer dependencies, or local configuration.
+Step 1 exists to tell those apart.
+
+## Non-negotiables
+
+1. **The upstream issue is filed before local code is changed** to route around the bug.
+2. **Never** modify anything under `node_modules/` (or add a `patch-package` patch, or vendor a
+   copy of upstream source) without explicit human approval.
+3. **Never** run `gh issue create` unprompted. Draft the issue, show it to the human, wait for a
+   clear yes, then file it. Filing an issue is an outward-facing action on a shared repo.
+4. **Any workaround needs explicit human approval** — present the options and the trade-offs, do
+   not pick one and start editing (see Step 6).
+5. **Be honest about what you verified.** Separate "confirmed by running it" from "suspected".
+   A confidently-wrong root cause wastes more upstream time than no root cause at all.
+
+---
+
+## Step 1 — Rule out the boring causes
+
+Do this before writing a single line of the issue.
+
+```bash
+# What is actually installed (the lockfile, not the range in package.json)?
+npm ls @genesislcap/<package>            # or: pnpm why @genesislcap/<package>
+
+# Is it the latest? Is there a newer patch or a prerelease dist-tag?
+npm view @genesislcap/<package> version
+npm view @genesislcap/<package> dist-tags
+
+# Are the @genesislcap/* packages on matching versions? Mixed majors/minors cause
+# symptoms that look exactly like upstream bugs but are dependency drift.
+npm ls --all 2>/dev/null | grep @genesislcap
+```
+
+Then confirm the calling code follows the documented API — read the package's own `dist/dts/*.d.ts`
+and README rather than assuming. If the answer is "we were holding it wrong", fix it locally and
+stop here; this rule is done.
+
+## Step 2 — Check it isn't already known or already fixed
+
+```bash
+# Open AND closed issues — a closed one may name the release that fixed it.
+gh issue list --repo genesislcap/foundation-ui --state all --search "<keywords>" --limit 20
+
+# Same for PRs — a fix may be merged but not yet released.
+gh pr list --repo genesislcap/foundation-ui --state all --search "<keywords>" --limit 20
+```
+
+Outcomes:
+
+- **An open issue matches** → don't file a duplicate. Add a comment with your new evidence
+  (your version, your repro, your environment) after the human approves, and link it in your report.
+- **A closed issue matches and a newer version exists** → the fix is likely released. Recommend the
+  upgrade instead of an issue.
+- **Nothing matches** → continue to Step 3.
+
+## Step 3 — Collect the evidence
+
+An upstream maintainer needs to reproduce this without access to your app. Gather:
+
+| What | How |
+| --- | --- |
+| Root-cause package + exact version | The package the broken code lives in, e.g. `@genesislcap/foundation-comms@15.3.1` |
+| Symptom package + exact version | Where it *appears* to break, if different, e.g. `@genesislcap/grid-pro@15.3.1` |
+| The offending code | Real path + quoted snippet from `node_modules/@genesislcap/<pkg>/dist/...` |
+| Minimal reproduction | Numbered steps. Say plainly whether you executed them or are proposing them |
+| Expected vs actual | Both stated as observable behaviour, not as internal state |
+| Environment | Framework + version (React 19, Angular, etc.), bundler, browser, and relevant third-party versions (`ag-grid-community`, `@microsoft/fast-element`, …) |
+| Evidence | Console output, network/websocket trace, screenshots — trimmed to the relevant lines |
+| Workaround status | What unblocks the app today (even if it's "nothing yet") |
+
+Redact anything client-confidential: hostnames, credentials, real user data, and business-specific
+resource names. Replace them with placeholders (`SOME_DATASERVER_QUERY`) — a repro does not need
+them to be real.
+
+## Step 4 — Draft the issue
+
+Title: a specific, searchable one-liner that names the mechanism, not just the symptom. No
+conventional-commit prefix.
+
+- Good: `sendForStream() defers DATA_LOGON via DOM.queueUpdate — StrictMode double-mount discards it, leaving every dataserver grid empty`
+- Bad: `Grid is empty`
+
+Body — use this structure (it mirrors
+[#2442](https://github.com/genesislcap/foundation-ui/issues/2442), a good reference report):
+
+````markdown
+## Package + version
+
+Root cause: **`@genesislcap/<pkg>@<version>`**
+Visible symptom in: **`@genesislcap/<pkg>@<version>`** (if different)
+
+From the consumer's `package.json`:
+
+```
+"@genesislcap/<pkg>": "<version>"
+"<relevant third-party dep>": "<version>"
+```
+
+## Summary
+
+One paragraph: the mechanism and its user-visible consequence.
+
+## Reproduction
+
+State up front whether this was confirmed end-to-end or is a proposed reduction.
+
+1. …
+2. …
+3. Observe: …
+
+## Expected vs Actual
+
+**Expected**
+- …
+
+**Actual**
+- …
+
+## Root cause
+
+`<pkg>/dist/<path>`:
+
+```js
+// the offending snippet, quoted
+```
+
+Explain why this is wrong. If parts are inferred rather than observed, say so explicitly.
+
+## Impact
+
+Who and what is affected — one app, every consumer using this component, dev-only, production.
+
+## Workaround in place downstream
+
+What the consumer project is doing right now to stay unblocked, or "none".
+
+## Environment
+
+- Framework: …
+- Browser / Node: …
+- Other relevant versions: …
+````
+
+Show the draft to the human. Do not file it yet.
+
+## Step 5 — File it (after the human says yes)
+
+Write the body to a temp file first — passing markdown inline mangles backticks and special
+characters:
+
+```bash
+gh issue create \
+  --repo genesislcap/foundation-ui \
+  --title "<title>" \
+  --body-file /tmp/upstream-issue.md \
+  --label "Bug" \
+  --label "<area label>"
+```
+
+Pick area labels from the repo's own list — `gh label list --repo genesislcap/foundation-ui --limit 100`.
+Common ones:
+
+| Area | Label |
+| --- | --- |
+| grid-pro, data-grid, rapid-grid-pro | `Grids` |
+| foundation-comms, datasources, websockets | `COMMS`, `Datasource` |
+| design system, FAST, rapid components | `Design System`, `Rapid` |
+| foundation-forms / criteria / filters | `Forms`, `Criteria` |
+| foundation-layout, golden/dynamic layout | `Layout` |
+| foundation-entity-management | `Entity Management` |
+| React/Angular/Vue wrappers, typings | `Frontends Compatibility` |
+| build, bundling, genx/CLI | `Build`, `Rollup & Webpack`, `CLI & GENX` |
+| production-blocking | `High Priority`, or `CRITICAL` if the app is down |
+
+Then delete the temp file, and report the issue URL back to the human.
+
+## Step 6 — Workaround: only after the issue exists, only with approval
+
+Filing the issue does not unblock this app. Once the issue URL exists:
+
+1. **Present the options**, with the cost of each — e.g. upgrade/downgrade, use a different
+   documented API, local subclass/override, wait for the upstream fix, `patch-package`.
+   Include "do nothing yet" when it is viable.
+2. **Wait for an explicit choice.** Do not start editing consumer code before that.
+3. **Once approved**, keep it minimal and make it self-deleting on upgrade:
+   - Mark every touched site with a marker comment carrying the issue URL and the removal condition:
+
+     ```ts
+     // UPSTREAM-WORKAROUND(genesislcap/foundation-ui#2442):
+     // foundation-comms defers DATA_LOGON via DOM.queueUpdate, so a StrictMode remount drops it.
+     // Remove when: @genesislcap/foundation-comms ships the fix (> 15.3.1) and this app upgrades.
+     ```
+
+   - Prefer wrapping over forking: a subclass, a decorator, or an adapter at one boundary beats a
+     vendored copy of upstream source scattered across the codebase.
+   - Never leave the workaround as the only record of the bug. The marker must name the issue.
+4. **Log it** in a single tracking file the team can grep at upgrade time (create it if absent —
+   `docs/upstream-workarounds.md`):
+
+   ````markdown
+   | Issue | Package + version | What we do locally | Remove when |
+   | --- | --- | --- | --- |
+   | genesislcap/foundation-ui#2442 | foundation-comms@15.3.1 | ... | fix released and adopted |
+   ````
+
+## Step 7 — Offer the upstream fix
+
+If the fix is small and you can see it, say so in the issue and offer a PR. `foundation-ui` accepts
+contributions from consumer teams — see its
+[CONTRIBUTING.md](https://github.com/genesislcap/foundation-ui/blob/master/CONTRIBUTING.md) for
+setup, commit format, and the PR template. A pre-release build can be cut from a branch so this app
+can validate the fix before it lands (`@genesislcap/<pkg>@<dist-tag>`); ask in the issue.
+
+## Never
+
+- Edit `node_modules/` directly, or add a `patch-package` patch, without approval — and never
+  without an issue link in the patch's commit message.
+- Present a suspected root cause as confirmed.
+- Paste client-confidential data (hostnames, credentials, real records) into a shared repo.
+- Delete, skip, or weaken a test to make an upstream bug invisible.
+- Ship a workaround with no marker comment and no issue reference.

package/dist/commands/agent-rules.d.ts

@@ -0,0 +1,6 @@
+declare const _default: (folder?: string, options?: {
+    tools?: string;
+    check?: boolean;
+}) => Promise<void>;
+export default _default;
+//# sourceMappingURL=agent-rules.d.ts.map

package/dist/commands/agent-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-rules.d.ts","sourceRoot":"","sources":["../../src/commands/agent-rules.ts"],"names":[],"mappings":"yBAuCE,eAAsB,EACtB,UAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO;AAFnD,wBAoDE"}

package/dist/commands/agent-rules.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const build_kit_1 = require("@genesislcap/build-kit");
+const consola_1 = tslib_1.__importDefault(require("consola"));
+const agent_rules_1 = require("../utils/agent-rules");
+/** The packaged rules live at the root of this package, alongside `bin` and `dist`. */
+const packagedRulesDir = () => (0, node_path_1.resolve)(__dirname, '../../agent-rules');
+const loadManifest = (rulesDir) => JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(rulesDir, 'manifest.json'), 'utf8'));
+const readRuleContents = (rulesDir, manifest) => manifest.rules.reduce((contents, rule) => {
+    contents[rule.file] = (0, node_fs_1.readFileSync)((0, node_path_1.join)(rulesDir, rule.file), 'utf8');
+    return contents;
+}, {});
+const resolveTools = (dir, requested) => {
+    if (!requested) {
+        return (0, agent_rules_1.detectTools)(dir);
+    }
+    try {
+        return (0, agent_rules_1.parseTools)(requested);
+    }
+    catch (error) {
+        // A typo in --tools is a user error, not a bug: report it without a stack trace.
+        consola_1.default.error(error.message);
+        process.exit(1);
+    }
+};
+exports.default = (...args_1) => tslib_1.__awaiter(void 0, [...args_1], void 0, function* (folder = process.cwd(), options = {}) {
+    const dir = (0, node_path_1.resolve)(folder);
+    const rulesDir = packagedRulesDir();
+    const manifest = loadManifest(rulesDir);
+    const ruleContents = readRuleContents(rulesDir, manifest);
+    const tools = resolveTools(dir, options.tools);
+    if (!tools.length) {
+        consola_1.default.warn(`No assistant detected in ${dir}. The rule files will be installed, but nothing will be wired up. Pass --tools claude,cursor,gemini,agents to wire one explicitly.`);
+    }
+    const planned = (0, agent_rules_1.planFiles)(dir, manifest, tools, ruleContents, (path) => (0, node_fs_1.readFileSync)(path, 'utf8'));
+    const drift = (0, agent_rules_1.findDrift)(dir, planned);
+    if (options.check) {
+        if (drift.length) {
+            consola_1.default.error(`Agent rules are out of date in ${dir}:`);
+            drift.forEach((file) => consola_1.default.log((0, build_kit_1.white)(`  ${(0, build_kit_1.bold)(file.path)} ${(0, node_fs_1.existsSync)((0, node_path_1.join)(dir, file.path)) ? 'differs' : 'missing'}`)));
+            consola_1.default.info('Run `genx agent-rules` to update.');
+            process.exit(1);
+        }
+        consola_1.default.success(`Agent rules are up to date (${manifest.rules.length} rule(s)).`);
+        return;
+    }
+    if (!drift.length) {
+        consola_1.default.info('Agent rules already up to date. Nothing to do.');
+        return;
+    }
+    drift.forEach((file) => {
+        const path = (0, node_path_1.join)(dir, file.path);
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+        (0, node_fs_1.writeFileSync)(path, file.contents, 'utf8');
+        consola_1.default.log((0, build_kit_1.white)(`  ${(0, build_kit_1.bold)(file.path)}`));
+    });
+    consola_1.default.success(`Installed ${manifest.rules.length} agent rule(s)${tools.length ? ` for: ${tools.join(', ')}` : ''}.`);
+    consola_1.default.info('Commit the changes so the whole team gets them.');
+});

package/dist/commands/index.d.ts

@@ -1,4 +1,8 @@
 export declare const commands: {
+    agentRules: () => Promise<(folder?: string, options?: {
+        tools?: string;
+        check?: boolean;
+    }) => Promise<void>>;
     clean: () => Promise<(paths?: string[]) => Promise<void>>;
     generateEventTypes: () => Promise<(folder?: string, options?: {
         fromMetadata?: string;

package/dist/commands/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,QAAQ;;;oBAEI,CAAC;;;;;;;CAMzB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,QAAQ;;aAYgoB,CAAC;aAAe,CAAC;;;;oBAVvpB,CAAA;;;;;;;CAOd,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,QAAQ,CAAC"}

package/dist/commands/index.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.commands = void 0;
 // lazy loading command definitions
 exports.commands = {
+    agentRules: () => Promise.resolve().then(() => __importStar(require('./agent-rules'))).then((r) => r.default),
     clean: () => Promise.resolve().then(() => __importStar(require('./clean'))).then((r) => r.default),
     generateEventTypes: () => Promise.resolve().then(() => __importStar(require('./generate-event-types'))).then((r) => r.default),
     run: () => Promise.resolve().then(() => __importStar(require('./run'))).then((r) => r.default),

package/dist/index.js

@@ -42,6 +42,23 @@ cli
     consola_1.consola.error(`Unknown generate type "${type}". Supported: event-types`);
     process.exit(1);
 }));
+cli
+    .command('agent-rules [folder]', 'Install shared AI agent rules into a project')
+    .option('-t, --tools <list>', 'Comma-separated assistants to wire: claude, cursor, gemini, agents (defaults to those detected)')
+    .option('-c, --check', 'Verify the installed rules are up to date, exit 1 otherwise (for CI)')
+    .action((folder, options) => tslib_1.__awaiter(void 0, void 0, void 0, function* () {
+    const action = yield commands_1.commands.agentRules();
+    yield action(folder, options);
+})).example(`
+  ${(0, build_kit_1.bold)('genx agent-rules')}
+    Install the shared rules into docs/agent-rules and wire up every assistant detected in the project
+
+  ${(0, build_kit_1.bold)('genx agent-rules --tools claude,cursor')}
+    Wire up Claude Code and Cursor explicitly
+
+  ${(0, build_kit_1.bold)('genx agent-rules --check')}
+    Fail if the installed rules are missing or out of date (use in CI)
+`);
 cli
     .command('clean [...paths]', 'Delete specified paths (defaults to dist folder)')
     .action((paths) => tslib_1.__awaiter(void 0, void 0, void 0, function* () {

package/dist/utils/agent-rules.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Shareable agent rules are markdown files that ship with this package and are installed into a
+ * consumer project by `genx agent-rules`. The rule body is tool-agnostic; per-assistant wiring is
+ * generated from the manifest below.
+ */
+export interface AgentRule {
+    /** File name of the rule markdown, relative to the packaged `agent-rules` folder. */
+    file: string;
+    /** Slug used for generated file names, e.g. the Cursor `.mdc`. */
+    name: string;
+    /** Human readable title, used in logs and generated pointers. */
+    title: string;
+    /** When the rule applies. Used as the Claude skill / pointer description. */
+    description: string;
+    /** Cursor's trigger phrasing for the `.mdc` front matter. */
+    cursorDescription: string;
+}
+export interface AgentRulesManifest {
+    version: number;
+    /** Where the rule markdown is installed inside the consumer project. */
+    targetDir: string;
+    rules: AgentRule[];
+}
+export declare const AGENT_TOOLS: readonly ["claude", "cursor", "gemini", "agents"];
+export type AgentTool = (typeof AGENT_TOOLS)[number];
+/** Entry file each assistant reads, for the tools wired via a managed block. */
+export declare const TOOL_ENTRY_FILES: Record<Exclude<AgentTool, 'cursor'>, string>;
+export declare const MANAGED_BEGIN = "<!-- BEGIN genx agent-rules -->";
+export declare const MANAGED_END = "<!-- END genx agent-rules -->";
+export interface PlannedFile {
+    /** Path relative to the consumer project root. */
+    path: string;
+    contents: string;
+}
+export type ExistsFn = (path: string) => boolean;
+export type ReadFn = (path: string) => string;
+/**
+ * Replaces the genx-managed block in `content`, or appends one when absent. Everything outside the
+ * markers is left alone — these files belong to the consumer project, not to us.
+ */
+export declare const upsertManagedBlock: (content: string, body: string) => string;
+/** Import line understood by Claude Code (`CLAUDE.md`) and Gemini CLI (`GEMINI.md`). */
+export declare const renderImportBlock: (rules: AgentRule[], targetDir: string) => string;
+/** Plain pointer for assistants without an import syntax (AGENTS.md, Copilot, Windsurf, …). */
+export declare const renderPointerBlock: (rules: AgentRule[], targetDir: string) => string;
+/** A fully generated Cursor rule that defers to the shared markdown. */
+export declare const renderCursorRule: (rule: AgentRule, targetDir: string) => string;
+/**
+ * Which assistants a project already uses. Wiring an assistant nobody uses is just litter, so we
+ * only touch what we can see evidence of.
+ */
+export declare const detectTools: (dir: string, exists?: ExistsFn) => AgentTool[];
+/** Parses and validates a `--tools` value. Throws on anything unknown rather than guessing. */
+export declare const parseTools: (value: string) => AgentTool[];
+/**
+ * Everything the command intends to write, as (path, contents) pairs. Kept separate from the
+ * writing itself so `--check` can compare against disk without touching it.
+ */
+export declare const planFiles: (dir: string, manifest: AgentRulesManifest, tools: AgentTool[], ruleContents: Record<string, string>, read: ReadFn, exists?: ExistsFn) => PlannedFile[];
+/** Planned files whose contents differ from what is on disk. */
+export declare const findDrift: (dir: string, planned: PlannedFile[], read?: ReadFn, exists?: ExistsFn) => PlannedFile[];
+//# sourceMappingURL=agent-rules.d.ts.map

package/dist/utils/agent-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-rules.d.ts","sourceRoot":"","sources":["../../src/utils/agent-rules.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED,eAAO,MAAM,WAAW,mDAAoD,CAAC;AAC7E,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,gFAAgF;AAChF,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,MAAM,CAIzE,CAAC;AAEF,eAAO,MAAM,aAAa,oCAAoC,CAAC;AAC/D,eAAO,MAAM,WAAW,kCAAkC,CAAC;AAE3D,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,QAAQ,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;AACjD,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,EAAE,MAAM,MAAM,KAAG,MAgBlE,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,iBAAiB,GAAI,OAAO,SAAS,EAAE,EAAE,WAAW,MAAM,KAAG,MAI5D,CAAC;AAEf,+FAA+F;AAC/F,eAAO,MAAM,kBAAkB,GAAI,OAAO,SAAS,EAAE,EAAE,WAAW,MAAM,KAAG,MAI7D,CAAC;AAEf,wEAAwE;AACxE,eAAO,MAAM,gBAAgB,GAAI,MAAM,SAAS,EAAE,WAAW,MAAM,KAAG,MAarE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,EAAE,SAAQ,QAAqB,KAAG,SAAS,EAQjF,CAAC;AAEF,+FAA+F;AAC/F,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,KAAG,SAAS,EAYnD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,SAAS,GACpB,KAAK,MAAM,EACX,UAAU,kBAAkB,EAC5B,OAAO,SAAS,EAAE,EAClB,cAAc,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,MAAM,MAAM,EACZ,SAAQ,QAAqB,KAC5B,WAAW,EA6Bb,CAAC;AAEF,gEAAgE;AAChE,eAAO,MAAM,SAAS,GACpB,KAAK,MAAM,EACX,SAAS,WAAW,EAAE,EACtB,OAAM,MAA6C,EACnD,SAAQ,QAAqB,KAC5B,WAAW,EAIV,CAAC"}

package/dist/utils/agent-rules.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findDrift = exports.planFiles = exports.parseTools = exports.detectTools = exports.renderCursorRule = exports.renderPointerBlock = exports.renderImportBlock = exports.upsertManagedBlock = exports.MANAGED_END = exports.MANAGED_BEGIN = exports.TOOL_ENTRY_FILES = exports.AGENT_TOOLS = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+exports.AGENT_TOOLS = ['claude', 'cursor', 'gemini', 'agents'];
+/** Entry file each assistant reads, for the tools wired via a managed block. */
+exports.TOOL_ENTRY_FILES = {
+    claude: 'CLAUDE.md',
+    gemini: 'GEMINI.md',
+    agents: 'AGENTS.md',
+};
+exports.MANAGED_BEGIN = '<!-- BEGIN genx agent-rules -->';
+exports.MANAGED_END = '<!-- END genx agent-rules -->';
+/**
+ * Replaces the genx-managed block in `content`, or appends one when absent. Everything outside the
+ * markers is left alone — these files belong to the consumer project, not to us.
+ */
+const upsertManagedBlock = (content, body) => {
+    const block = `${exports.MANAGED_BEGIN}\n${body.trim()}\n${exports.MANAGED_END}`;
+    const begin = content.indexOf(exports.MANAGED_BEGIN);
+    const end = content.indexOf(exports.MANAGED_END);
+    if (begin !== -1 && end > begin) {
+        const before = content.slice(0, begin);
+        const after = content.slice(end + exports.MANAGED_END.length);
+        return `${before}${block}${after}`;
+    }
+    if (!content.trim()) {
+        return `${block}\n`;
+    }
+    return `${content.replace(/\s*$/, '')}\n\n${block}\n`;
+};
+exports.upsertManagedBlock = upsertManagedBlock;
+/** Import line understood by Claude Code (`CLAUDE.md`) and Gemini CLI (`GEMINI.md`). */
+const renderImportBlock = (rules, targetDir) => [
+    '<!-- Installed by `genx agent-rules`. Re-run it to update; edits inside this block are lost. -->',
+    ...rules.map((rule) => `@${targetDir}/${rule.file}`),
+].join('\n');
+exports.renderImportBlock = renderImportBlock;
+/** Plain pointer for assistants without an import syntax (AGENTS.md, Copilot, Windsurf, …). */
+const renderPointerBlock = (rules, targetDir) => [
+    '<!-- Installed by `genx agent-rules`. Re-run it to update; edits inside this block are lost. -->',
+    ...rules.map((rule) => `- ${rule.description} Read and follow \`${targetDir}/${rule.file}\`.`),
+].join('\n');
+exports.renderPointerBlock = renderPointerBlock;
+/** A fully generated Cursor rule that defers to the shared markdown. */
+const renderCursorRule = (rule, targetDir) => `---
+description: ${rule.cursorDescription}
+alwaysApply: false
+---
+
+<!-- Installed by \`genx agent-rules\`. Re-run it to update; local edits are lost. -->
+
+# ${rule.title}
+
+@${targetDir}/${rule.file}
+
+If this reference does not resolve, open \`${targetDir}/${rule.file}\` and follow it directly.
+`;
+exports.renderCursorRule = renderCursorRule;
+/**
+ * Which assistants a project already uses. Wiring an assistant nobody uses is just litter, so we
+ * only touch what we can see evidence of.
+ */
+const detectTools = (dir, exists = node_fs_1.existsSync) => {
+    const markers = {
+        claude: ['CLAUDE.md', '.claude'],
+        cursor: ['.cursor', '.cursorrules'],
+        gemini: ['GEMINI.md', '.gemini'],
+        agents: ['AGENTS.md'],
+    };
+    return exports.AGENT_TOOLS.filter((tool) => markers[tool].some((marker) => exists((0, node_path_1.join)(dir, marker))));
+};
+exports.detectTools = detectTools;
+/** Parses and validates a `--tools` value. Throws on anything unknown rather than guessing. */
+const parseTools = (value) => {
+    const requested = value
+        .split(',')
+        .map((tool) => tool.trim().toLowerCase())
+        .filter(Boolean);
+    const unknown = requested.filter((tool) => !exports.AGENT_TOOLS.includes(tool));
+    if (unknown.length) {
+        throw new Error(`Unknown agent tool(s): ${unknown.join(', ')}. Supported: ${exports.AGENT_TOOLS.join(', ')}`);
+    }
+    return exports.AGENT_TOOLS.filter((tool) => requested.includes(tool));
+};
+exports.parseTools = parseTools;
+/**
+ * Everything the command intends to write, as (path, contents) pairs. Kept separate from the
+ * writing itself so `--check` can compare against disk without touching it.
+ */
+const planFiles = (dir, manifest, tools, ruleContents, read, exists = node_fs_1.existsSync) => {
+    const { targetDir, rules } = manifest;
+    const planned = rules.map((rule) => ({
+        path: `${targetDir}/${rule.file}`,
+        contents: ruleContents[rule.file],
+    }));
+    tools.forEach((tool) => {
+        if (tool === 'cursor') {
+            rules.forEach((rule) => {
+                planned.push({
+                    path: `.cursor/rules/${rule.name}.mdc`,
+                    contents: (0, exports.renderCursorRule)(rule, targetDir),
+                });
+            });
+            return;
+        }
+        const entryFile = exports.TOOL_ENTRY_FILES[tool];
+        const entryPath = (0, node_path_1.join)(dir, entryFile);
+        const current = exists(entryPath) ? read(entryPath) : '';
+        const body = tool === 'agents'
+            ? (0, exports.renderPointerBlock)(rules, targetDir)
+            : (0, exports.renderImportBlock)(rules, targetDir);
+        planned.push({ path: entryFile, contents: (0, exports.upsertManagedBlock)(current, body) });
+    });
+    return planned;
+};
+exports.planFiles = planFiles;
+/** Planned files whose contents differ from what is on disk. */
+const findDrift = (dir, planned, read = (path) => (0, node_fs_1.readFileSync)(path, 'utf8'), exists = node_fs_1.existsSync) => planned.filter((file) => {
+    const path = (0, node_path_1.join)(dir, file.path);
+    return !exists(path) || read(path) !== file.contents;
+});
+exports.findDrift = findDrift;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/genx",
   "description": "Genx CLI",
-  "version": "15.23.0",
+  "version": "15.23.1-agent-rules.1",
   "license": "SEE LICENSE IN license.txt",
   "engines": {
     "node": ">=22.0.0"
@@ -10,6 +10,7 @@
     "build": "npm run clean && tsc -b ./tsconfig.json",
     "clean": "rimraf dist temp tsconfig.tsbuildinfo",
     "dev": "tsc -b ./tsconfig.json -w",
+    "test": "genx test",
     "lint": "genx lint -l ox",
     "lint:fix": "genx lint -l ox --fix"
   },
@@ -17,18 +18,21 @@
     "genx": "./bin/genx"
   },
   "dependencies": {
-    "@genesislcap/build-kit": "15.23.0",
-    "@genesislcap/eslint-stylelint-builder": "15.23.0",
-    "@genesislcap/event-type-codegen": "15.23.0",
-    "@genesislcap/rollup-builder": "15.23.0",
-    "@genesislcap/ts-builder": "15.23.0",
-    "@genesislcap/uvu-playwright-builder": "15.23.0",
-    "@genesislcap/vite-builder": "15.23.0",
-    "@genesislcap/webpack-builder": "15.23.0",
+    "@genesislcap/build-kit": "15.23.1-agent-rules.1",
+    "@genesislcap/eslint-stylelint-builder": "15.23.1-agent-rules.1",
+    "@genesislcap/event-type-codegen": "15.23.1-agent-rules.1",
+    "@genesislcap/rollup-builder": "15.23.1-agent-rules.1",
+    "@genesislcap/ts-builder": "15.23.1-agent-rules.1",
+    "@genesislcap/uvu-playwright-builder": "15.23.1-agent-rules.1",
+    "@genesislcap/vite-builder": "15.23.1-agent-rules.1",
+    "@genesislcap/webpack-builder": "15.23.1-agent-rules.1",
     "cac": "^6.7.14",
     "consola": "^3.0.2",
     "serve-handler": "^6.1.5"
   },
+  "devDependencies": {
+    "@genesislcap/foundation-testing": "15.23.1-agent-rules.1"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/genesislcap/foundation-ui.git",