@jazpiper/rules-doctor 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.3.0 - 2026-02-25
+
+- Added `copilot` adapter support for `.github/copilot-instructions.md`.
+- Switched Copilot output to marker-managed mode to preserve user-authored content.
+- Added target presets for `init` (`all`, `core`, `copilot`).
+- Added `preset apply` command for applying presets to existing `.agentrules/rules.yaml`.
+- Added CI workflow template for drift detection via `rules-doctor check`.
+- Expanded tests for shared `AGENTS.md`, Copilot marker re-sync, and `--import` + preset behavior.
+- Improved README with troubleshooting and CI examples.
+
+## 0.2.0 - 2026-02-25
+
+- Added multi-target adapters for `claude`, `codex`, `cursor`, `gemini`, and `opencode`.
+- Added `init --import`, dry-run default for `sync`, drift `check`, and structural `doctor`.

package/README.md

@@ -1,6 +1,14 @@
 # @jazpiper/rules-doctor
 
-`rules-doctor` is a Node.js CLI (TypeScript) that keeps agent instruction files in sync from one source of truth: `.agentrules/rules.yaml`.
+`rules-doctor` keeps coding-rule files in sync across multiple agent CLIs from one source of truth: `.agentrules/rules.yaml`.
+
+It is optimized for real project adoption:
+- import existing docs (`init --import`)
+- target presets (`init --preset all|core|copilot`)
+- safe previews by default (`sync` is dry-run unless `--write`)
+- drift detection for CI (`check`)
+
+All paths are resolved from project root (`.git` ancestor), not current subdirectory.
 
 ## Install
 
@@ -8,75 +16,169 @@
 npm install -D @jazpiper/rules-doctor
 ```
 
-Or run directly:
+Run with:
 
 ```bash
-npx @jazpiper/rules-doctor init
+npx rules-doctor --help
 ```
 
-## Usage
+## Quick Start
 
-### 1) Initialize rules
+### 1) Initialize (recommended with import)
 
 ```bash
-rules-doctor init
+npx rules-doctor init --import
 ```
 
-Creates `.agentrules/rules.yaml` if it does not exist.
+- Creates `.agentrules/rules.yaml`
+- Reads existing docs when found (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`)
+- Writes `.agentrules/import-report.md`
+
+Preset example (Copilot only):
+
+```bash
+npx rules-doctor init --preset copilot
+```
 
-- If `package.json` has scripts for `lint`, `test`, or `build`, they are inferred as:
-  - `npm run lint`
-  - `npm run test`
-  - `npm run build`
-- Missing scripts are created as TODO placeholders.
+Preset meanings:
+- `all`: all built-in targets enabled
+- `core`: `claude`, `codex`, `opencode`, `cursor`, `gemini`
+- `copilot`: only `copilot` enabled
 
-### 2) Sync generated docs
+Apply preset to an existing `.agentrules/rules.yaml`:
 
 ```bash
-rules-doctor sync
-rules-doctor sync --target claude
-rules-doctor sync --target codex
+npx rules-doctor preset apply copilot --write
 ```
 
-Generates/updates:
-- `CLAUDE.md` (fully managed)
-- `AGENTS.md` (only content inside markers is managed)
+### 2) Preview changes safely
 
-Managed marker block in `AGENTS.md`:
+```bash
+npx rules-doctor sync --diff
+```
 
-```md
-<!-- RULES_DOCTOR:BEGIN -->
-... managed content ...
-<!-- RULES_DOCTOR:END -->
+`sync` is dry-run by default. Nothing is written yet.
+
+### 3) Apply changes
+
+```bash
+npx rules-doctor sync --write
 ```
 
-If markers are missing, a new managed block is appended to the end of `AGENTS.md`.
+Optional backups:
 
-### 3) Analyze docs
+```bash
+npx rules-doctor sync --write --backup
+```
+
+### 4) Verify drift in CI/local
 
 ```bash
-rules-doctor analyze
+npx rules-doctor check
 ```
 
-Reads `CLAUDE.md` and `AGENTS.md`, then prints a concise report about:
-- missing markers
-- missing verify commands (`lint`/`test`/`build`)
-- obvious contradictions (simple heuristics)
+Returns non-zero when generated targets are out of sync.
 
-## Development
+## Supported Targets
 
 ```bash
-npm ci
-npm run build
+npx rules-doctor targets list
 ```
 
-## License
+Built-in adapters:
+- `claude` -> `CLAUDE.md` (full-managed)
+- `codex` -> `AGENTS.md` (marker-managed)
+- `copilot` -> `.github/copilot-instructions.md` (marker-managed, preserves existing text outside managed block)
+- `opencode` -> `AGENTS.md` (marker-managed)
+- `cursor` -> `.cursor/rules/rules-doctor.mdc` (full-managed)
+- `gemini` -> `GEMINI.md` (full-managed)
 
-MIT
+## Command Reference
+
+### `init`
 
+```bash
+npx rules-doctor init [--import]
+npx rules-doctor init [--import] [--preset all|core|copilot]
+```
 
-## CI
+### `preset apply`
 
-This repo includes a GitHub Actions workflow template at `docs/workflows/ci.yml`.
+```bash
+npx rules-doctor preset apply <all|core|copilot> [--diff] [--write]
+```
 
-If you want CI, copy it to `.github/workflows/ci.yml` and push the change.
+### `sync`
+
+```bash
+npx rules-doctor sync [--target all|claude,codex,...] [--diff] [--write] [--backup]
+```
+
+### `check`
+
+```bash
+npx rules-doctor check [--target all|claude,codex,...] [--diff]
+```
+
+### `analyze`
+
+```bash
+npx rules-doctor analyze [--strict]
+```
+
+### `doctor`
+
+```bash
+npx rules-doctor doctor [--strict]
+```
+
+## CI Template
+
+Copy [docs/workflows/rules-doctor-check.yml](docs/workflows/rules-doctor-check.yml) to your repository as `.github/workflows/rules-doctor-check.yml`.
+It runs `npx rules-doctor check` on push and pull requests.
+
+Inline workflow example:
+
+```yaml
+name: Rules Doctor Check
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  rules-doctor:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+      - run: npm ci
+      - run: npx rules-doctor check
+```
+
+## Troubleshooting
+
+- `rules-doctor: command not found` after `npm install -D @jazpiper/rules-doctor`:
+  - Use `npx rules-doctor ...` (recommended for local dev dependency).
+  - Or add an npm script in your project: `"rules:check": "rules-doctor check"`, then run `npm run rules:check`.
+  - Global install (`npm i -g @jazpiper/rules-doctor`) works, but local + `npx` is safer for version consistency.
+- `init` says `rules.yaml already exists`:
+  - Use `npx rules-doctor preset apply <preset> --write` to change target defaults on an existing project.
+
+## Rules Schema (v2 Draft)
+
+See [docs/rules-v2-draft.yaml](docs/rules-v2-draft.yaml).
+
+## Development
+
+```bash
+npm ci
+npm test
+```
+
+## License
+
+MIT

package/dist/adapters/claude.js

@@ -0,0 +1,31 @@
+const { formatCommands, formatList } = require("./common");
+
+module.exports = {
+  id: "claude",
+  name: "Claude Code",
+  description: "Generate CLAUDE.md from rules.yaml.",
+  defaultPath: "CLAUDE.md",
+  management: "full",
+  render(rules) {
+    return [
+      "# CLAUDE.md",
+      "",
+      "## Mission",
+      rules.mission,
+      "",
+      "## Workflow",
+      formatList(rules.workflow),
+      "",
+      "## Commands",
+      formatCommands(rules.commands),
+      "",
+      "## Done",
+      formatList(rules.done),
+      "",
+      "## Approvals",
+      `- Mode: \`${rules.approvals.mode}\``,
+      ...rules.approvals.notes.map((note) => `- ${note}`),
+      "",
+    ].join("\n");
+  },
+};

package/dist/adapters/codex.js

@@ -0,0 +1,14 @@
+const { renderManagedRulesBody } = require("./common");
+
+module.exports = {
+  id: "codex",
+  name: "Codex CLI",
+  description: "Manage AGENTS.md via marker-managed section.",
+  defaultPath: "AGENTS.md",
+  management: "marker",
+  markerBegin: "<!-- RULES_DOCTOR:BEGIN -->",
+  markerEnd: "<!-- RULES_DOCTOR:END -->",
+  render(rules) {
+    return renderManagedRulesBody(rules);
+  },
+};

package/dist/adapters/common.js

@@ -0,0 +1,54 @@
+function formatList(items) {
+  if (!Array.isArray(items) || items.length === 0) {
+    return "- (none)";
+  }
+  return items.map((item) => `- ${item}`).join("\n");
+}
+
+function formatCommands(commands) {
+  if (!commands || typeof commands !== "object") {
+    return "- (none)";
+  }
+
+  const preferredOrder = ["lint", "test", "build"];
+  const names = [
+    ...preferredOrder.filter((name) => Object.prototype.hasOwnProperty.call(commands, name)),
+    ...Object.keys(commands).filter((name) => !preferredOrder.includes(name)),
+  ];
+
+  if (names.length === 0) {
+    return "- (none)";
+  }
+
+  return names.map((name) => `- ${name}: \`${commands[name]}\``).join("\n");
+}
+
+function renderManagedRulesBody(rules) {
+  return [
+    "## rules-doctor Managed Rules",
+    "Generated from `.agentrules/rules.yaml`. Edit that file, then run `rules-doctor sync`.",
+    "",
+    "### Mission",
+    rules.mission,
+    "",
+    "### Workflow",
+    formatList(rules.workflow),
+    "",
+    "### Commands",
+    formatCommands(rules.commands),
+    "",
+    "### Done",
+    formatList(rules.done),
+    "",
+    "### Approvals",
+    `- Policy: \`${rules.approvals.mode}\``,
+    ...rules.approvals.notes.map((note) => `- ${note}`),
+    "",
+  ].join("\n");
+}
+
+module.exports = {
+  formatCommands,
+  formatList,
+  renderManagedRulesBody,
+};

package/dist/adapters/copilot.js

@@ -0,0 +1,15 @@
+const { renderManagedRulesBody } = require("./common");
+
+module.exports = {
+  id: "copilot",
+  name: "GitHub Copilot",
+  description:
+    "Manage .github/copilot-instructions.md via marker-managed section to preserve user content.",
+  defaultPath: ".github/copilot-instructions.md",
+  management: "marker",
+  markerBegin: "<!-- RULES_DOCTOR:COPILOT:BEGIN -->",
+  markerEnd: "<!-- RULES_DOCTOR:COPILOT:END -->",
+  render(rules) {
+    return ["# Copilot Instructions", "", renderManagedRulesBody(rules)].join("\n");
+  },
+};

package/dist/adapters/cursor.js

@@ -0,0 +1,19 @@
+const { renderManagedRulesBody } = require("./common");
+
+module.exports = {
+  id: "cursor",
+  name: "Cursor",
+  description: "Manage .cursor/rules/rules-doctor.mdc as an always-applied project rule.",
+  defaultPath: ".cursor/rules/rules-doctor.mdc",
+  management: "full",
+  render(rules) {
+    return [
+      "---",
+      "description: rules-doctor managed coding rules",
+      "alwaysApply: true",
+      "---",
+      "",
+      renderManagedRulesBody(rules),
+    ].join("\n");
+  },
+};

package/dist/adapters/gemini.js

@@ -0,0 +1,12 @@
+const { renderManagedRulesBody } = require("./common");
+
+module.exports = {
+  id: "gemini",
+  name: "Gemini CLI",
+  description: "Generate GEMINI.md managed instruction file.",
+  defaultPath: "GEMINI.md",
+  management: "full",
+  render(rules) {
+    return ["# GEMINI.md", "", renderManagedRulesBody(rules)].join("\n");
+  },
+};

package/dist/adapters/index.js

@@ -0,0 +1,14 @@
+const claude = require("./claude");
+const codex = require("./codex");
+const copilot = require("./copilot");
+const cursor = require("./cursor");
+const gemini = require("./gemini");
+const opencode = require("./opencode");
+
+const ADAPTERS = [claude, codex, copilot, cursor, gemini, opencode];
+const ADAPTERS_BY_ID = Object.fromEntries(ADAPTERS.map((adapter) => [adapter.id, adapter]));
+
+module.exports = {
+  ADAPTERS,
+  ADAPTERS_BY_ID,
+};

package/dist/adapters/opencode.js

@@ -0,0 +1,14 @@
+const { renderManagedRulesBody } = require("./common");
+
+module.exports = {
+  id: "opencode",
+  name: "OpenCode CLI",
+  description: "Manage AGENTS.md via marker-managed section (OpenCode rules).",
+  defaultPath: "AGENTS.md",
+  management: "marker",
+  markerBegin: "<!-- RULES_DOCTOR:BEGIN -->",
+  markerEnd: "<!-- RULES_DOCTOR:END -->",
+  render(rules) {
+    return renderManagedRulesBody(rules);
+  },
+};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};