aioengine 0.1.2 → 0.1.4

package/README.md

@@ -4,21 +4,49 @@ AI change control for developers using Claude Code, Cursor, Codex, Copilot, and
 
 aioengine helps you review AI-generated code before you trust it. It scans your repo for missing guardrails, checks changed files for risky edits, and flags when AI may have wandered outside the requested task.
 
+## Quick start
+
+Run aioengine in any JavaScript or TypeScript project:
+
+```bash
+npx aioengine check
+```
+
+Then set up AI coding guardrails:
+
+```bash
+npx aioengine init
+```
+
+After your AI coding tool makes changes, review them before committing:
+
+```bash
+npx aioengine scope "update landing page headline"
+npx aioengine review
+```
+
+In CI or pull request workflows:
+
+```bash
+npx aioengine ci --task "update landing page headline"
+```
+
 ## Commands
 
 ```bash
-aioengine init
-aioengine check
-aioengine scope "add init command"
-aioengine review
-aioengine rules
+npx aioengine init
+npx aioengine check
+npx aioengine scope "add init command"
+npx aioengine review
+npx aioengine ci --task "add init command"
+npx aioengine rules
 ```
 
 ## Why aioengine exists
 
 AI coding tools can move fast, but review becomes the bottleneck.
 
-A simple prompt can lead to unexpected changes in sensitive files like auth, billing, database migrations, environment config, deployment settings, or dependency files.
+A simple prompt can lead to unexpected changes in sensitive files like auth, billing, database migrations, environment config, deployment settings, dependency files, or CI workflows.
 
 aioengine helps answer:
 
@@ -26,12 +54,14 @@ aioengine helps answer:
 - Did AI change files outside the task?
 - Did AI add or modify dependencies?
 - Does this repo have AI coding rules?
-- What should I review before committing?
+- What should I review before committing or merging?
 
 ## `aioengine init`
 
 Sets up aioengine in your repo.
 
+Creates missing files only. aioengine will not overwrite an existing `CLAUDE.md`.
+
 Creates:
 
 ```txt
@@ -40,10 +70,16 @@ CLAUDE.md
 .cursor/rules/aioengine.mdc
 ```
 
+If `CLAUDE.md` already exists, aioengine leaves it untouched and saves suggested rules to:
+
+```txt
+.aioengine/suggested-claude-rules.md
+```
+
 Run:
 
 ```bash
-aioengine init
+npx aioengine init
 ```
 
 ## `aioengine check`
@@ -66,7 +102,7 @@ Checks for:
 Run:
 
 ```bash
-aioengine check
+npx aioengine check
 ```
 
 ## `aioengine scope`
@@ -76,10 +112,10 @@ Checks whether changed files match the task you gave your AI coding tool.
 Example:
 
 ```bash
-aioengine scope "update landing page headline"
+npx aioengine scope "update landing page headline"
 ```
 
-If the task sounds like a UI change but AI modified billing, database, env, dependency, or deployment files, aioengine will flag possible scope drift.
+If the task sounds like a UI change but AI modified billing, database, env, dependency, CLI, or deployment files, aioengine will flag possible scope drift.
 
 ## `aioengine review`
 
@@ -88,7 +124,7 @@ Reviews current uncommitted changes for risky files.
 Run:
 
 ```bash
-aioengine review
+npx aioengine review
 ```
 
 aioengine will flag changes to files that often deserve extra review, such as:
@@ -101,6 +137,52 @@ aioengine will flag changes to files that often deserve extra review, such as:
 - dependency files
 - GitHub workflow files
 
+## `aioengine ci`
+
+Runs aioengine checks in CI or pull request workflows.
+
+Run:
+
+```bash
+npx aioengine ci --task "update landing page headline"
+```
+
+In GitHub Actions, aioengine will try to detect changed files from the pull request context. If a task is available from the PR title, event payload, or `AIOENGINE_TASK`, it can flag possible scope drift.
+
+By default:
+
+- possible scope drift fails the CI check
+- risky files warn but do not fail the CI check
+
+Example GitHub Actions step:
+
+```yaml
+- name: Run aioengine
+  run: npx aioengine ci
+```
+
+For more reliable PR diffs, use checkout with full history:
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+
+- name: Run aioengine
+  run: npx aioengine ci
+```
+
+You can also pass a task manually:
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+
+- name: Run aioengine
+  run: npx aioengine ci --task "update landing page headline"
+```
+
 ## `aioengine rules`
 
 Generates starter AI coding rules for Claude Code and Cursor.
@@ -108,26 +190,36 @@ Generates starter AI coding rules for Claude Code and Cursor.
 Run:
 
 ```bash
-aioengine rules
+npx aioengine rules
+```
+
+Creates missing files only. aioengine will not overwrite an existing `CLAUDE.md`.
+
+If `CLAUDE.md` already exists, suggested Claude rules are saved to:
+
+```txt
+.aioengine/suggested-claude-rules.md
 ```
 
-This creates or skips:
+This command creates or skips:
 
 ```txt
 CLAUDE.md
 .cursor/rules/aioengine.mdc
+.aioengine/suggested-claude-rules.md
 ```
 
 ## Example workflow
 
 ```bash
-aioengine init
-aioengine check
+npx aioengine init
+npx aioengine check
 
 # Ask Claude, Cursor, Codex, or another AI coding tool to make a change.
 
-aioengine scope "update landing page headline"
-aioengine review
+npx aioengine scope "update landing page headline"
+npx aioengine review
+npx aioengine ci --task "update landing page headline"
 ```
 
 ## Current status

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aioengine",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "AI change control for developers using AI coding tools.",
   "main": "./src/index.js",
   "scripts": {
@@ -9,7 +9,8 @@
     "review": "node ./src/index.js review",
     "rules": "node ./src/index.js rules",
     "scope": "node ./src/index.js scope",
-    "init": "node ./src/index.js init"
+    "init": "node ./src/index.js init",
+    "ci": "node ./src/index.js ci"
   },
   "keywords": [
     "ai",

package/src/index.js

@@ -35,6 +35,12 @@ program
     runReview();
   });
 
+program
+  .command("ci")
+  .description("Run aioengine review checks in CI and pull request workflows.")
+  .option("--task <task>", "Task description to compare changed files against")
+  .action((options) => runCi(options));
+
 program
   .command("scope")
   .description("Check whether changed files match the requested task.")
@@ -62,7 +68,6 @@ function runInit() {
 
   const aioengineDir = ".aioengine";
   const configPath = path.join(aioengineDir, "config.json");
-  const claudePath = "CLAUDE.md";
   const cursorDir = ".cursor/rules";
   const cursorPath = path.join(cursorDir, "aioengine.mdc");
 
@@ -92,12 +97,7 @@ function runInit() {
     skipped.push(configPath);
   }
 
-  if (!exists(claudePath, root)) {
-    fs.writeFileSync(path.join(root, claudePath), getClaudeRules());
-    created.push(claudePath);
-  } else {
-    skipped.push(claudePath);
-  }
+  createClaudeRulesSafely(root, created, skipped);
 
   if (!exists(cursorDir, root)) {
     fs.mkdirSync(path.join(root, cursorDir), { recursive: true });
@@ -113,6 +113,14 @@ function runInit() {
   printSection("Created", created, "green");
   printSection("Skipped", skipped, "yellow");
 
+  if (skipped.includes("CLAUDE.md already exists")) {
+    console.log(
+      `\n${pc.dim(
+        "aioengine did not modify your existing CLAUDE.md. Suggested Claude rules were saved to .aioengine/suggested-claude-rules.md if that file did not already exist."
+      )}`
+    );
+  }
+
   console.log(pc.bold("Next steps:"));
   console.log(`  1. Run ${pc.cyan("aioengine check")}`);
   console.log(`  2. Make or review AI-generated changes`);
@@ -273,6 +281,112 @@ function runReview() {
   }
 }
 
+function runCi(options = {}) {
+  printHeader("aioengine CI");
+
+  const root = getProjectRoot();
+
+  if (!isInsideGitRepo()) {
+    console.log(
+      `${pc.red("✗")} No Git repo detected. aioengine ci must run inside a Git repository.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const task = options.task || getCiTask();
+  const files = getCiChangedFiles(root);
+
+  console.log(`${pc.dim("Project:")} ${root}`);
+
+  if (isGitHubActions()) {
+    console.log(`${pc.dim("Environment:")} GitHub Actions`);
+  } else {
+    console.log(`${pc.dim("Environment:")} Local / unknown CI`);
+  }
+
+  if (task) {
+    console.log(`${pc.dim("Task:")} ${task}`);
+  } else {
+    console.log(
+      `${pc.yellow("!")} No task detected. Scope checks will be less precise.`
+    );
+  }
+
+  if (files.length === 0) {
+    console.log(pc.green("\nNo changed files found."));
+    return;
+  }
+
+  const profile = task ? inferTaskProfile(task) : null;
+  const riskyFiles = files.filter(isRiskyFile);
+  const outOfScopeFiles = profile
+    ? files.filter((file) => isProbablyOutOfScope(file, profile))
+    : [];
+
+  if (profile) {
+    console.log(`${pc.dim("Detected task type:")} ${profile.label}`);
+  }
+
+  console.log(`${pc.dim("Changed files:")} ${files.length}\n`);
+
+  for (const file of files) {
+    const risky = riskyFiles.includes(file);
+    const outOfScope = outOfScopeFiles.includes(file);
+
+    if (outOfScope) {
+      console.log(`  ${pc.red("✗")} ${file} ${pc.red("— possible scope drift")}`);
+    } else if (risky) {
+      console.log(`  ${pc.yellow("!")} ${file} ${pc.yellow("— review carefully")}`);
+    } else {
+      console.log(`  ${pc.green("✓")} ${file}`);
+    }
+  }
+
+  const hasScopeDrift = outOfScopeFiles.length > 0;
+  const hasRiskyFiles = riskyFiles.length > 0;
+
+  if (hasScopeDrift) {
+    console.log(pc.yellow("\nCI review recommended"));
+
+    printSection(
+      "Possible scope drift",
+      outOfScopeFiles.map(
+        (file) => `Possible out-of-scope file changed: ${file}`
+      ),
+      "warning"
+    );
+
+    if (hasRiskyFiles) {
+      printSection(
+        "Risky files",
+        riskyFiles.map((file) => `High-risk file changed: ${file}`),
+        "warning"
+      );
+    }
+
+    console.log(
+      pc.dim(
+        "\nRecommendation: Review these changes before merging. aioengine is failing this CI check because possible scope drift was detected."
+      )
+    );
+
+    process.exitCode = 1;
+    return;
+  }
+
+  if (hasRiskyFiles) {
+    console.log(
+      pc.yellow(
+        "\nRisky files were changed. aioengine is allowing this check to pass, but these files should receive extra human review."
+      )
+    );
+    return;
+  }
+
+  console.log(pc.green("\nNo obvious AI change-control issues detected."));
+}
+
 function runScope(task) {
   printHeader("aioengine Scope");
 
@@ -382,19 +496,13 @@ function runRules() {
 
   const root = getProjectRoot();
 
-  const claudePath = "CLAUDE.md";
   const cursorDir = ".cursor/rules";
   const cursorPath = path.join(cursorDir, "aioengine.mdc");
 
   const created = [];
   const skipped = [];
 
-  if (!exists(claudePath, root)) {
-    fs.writeFileSync(path.join(root, claudePath), getClaudeRules());
-    created.push(claudePath);
-  } else {
-    skipped.push(claudePath);
-  }
+  createClaudeRulesSafely(root, created, skipped);
 
   if (!exists(cursorDir, root)) {
     fs.mkdirSync(path.join(root, cursorDir), { recursive: true });
@@ -410,6 +518,14 @@ function runRules() {
   printSection("Created", created, "green");
   printSection("Skipped", skipped, "yellow");
 
+  if (skipped.includes("CLAUDE.md already exists")) {
+    console.log(
+      `\n${pc.dim(
+        "aioengine did not modify your existing CLAUDE.md. Suggested Claude rules were saved to .aioengine/suggested-claude-rules.md if that file did not already exist."
+      )}`
+    );
+  }
+
   console.log(pc.bold("Next step:"));
   console.log(`  Run ${pc.cyan("aioengine check")} again.`);
 }
@@ -839,6 +955,37 @@ function getDefaultConfig() {
   };
 }
 
+function createClaudeRulesSafely(root, created, skipped) {
+  const claudePath = path.join(root, "CLAUDE.md");
+  const aioengineDir = path.join(root, ".aioengine");
+  const suggestedPath = path.join(
+    root,
+    ".aioengine",
+    "suggested-claude-rules.md"
+  );
+
+  if (!fs.existsSync(aioengineDir)) {
+    fs.mkdirSync(aioengineDir, { recursive: true });
+    created.push(".aioengine");
+  }
+
+  if (!fs.existsSync(claudePath)) {
+    fs.writeFileSync(claudePath, getClaudeRules(), "utf8");
+    created.push("CLAUDE.md");
+    return;
+  }
+
+  skipped.push("CLAUDE.md already exists");
+
+  if (!fs.existsSync(suggestedPath)) {
+    fs.writeFileSync(suggestedPath, getClaudeRules(), "utf8");
+    created.push(".aioengine/suggested-claude-rules.md");
+    return;
+  }
+
+  skipped.push(".aioengine/suggested-claude-rules.md already exists");
+}
+
 function getClaudeRules() {
   return `# AI Coding Rules
 
@@ -897,6 +1044,98 @@ For UI-only tasks, avoid backend, API, database, and config changes.
 `;
 }
 
+function isGitHubActions() {
+  return process.env.GITHUB_ACTIONS === "true";
+}
+
+function getCiTask() {
+  const explicitTask = process.env.AIOENGINE_TASK;
+
+  if (explicitTask) {
+    return explicitTask;
+  }
+
+  const eventPath = process.env.GITHUB_EVENT_PATH;
+
+  if (!eventPath || !fs.existsSync(eventPath)) {
+    return "";
+  }
+
+  try {
+    const event = JSON.parse(fs.readFileSync(eventPath, "utf8"));
+
+    return (
+      event.pull_request?.title ||
+      event.issue?.title ||
+      event.head_commit?.message ||
+      ""
+    );
+  } catch {
+    return "";
+  }
+}
+
+function getCiChangedFiles(root) {
+  if (isGitHubActions()) {
+    const files = getGitHubActionsChangedFiles(root);
+
+    if (files.length > 0) {
+      return files;
+    }
+  }
+
+  return getChangedFiles(root);
+}
+
+function getGitHubActionsChangedFiles(root) {
+  const baseRef = process.env.GITHUB_BASE_REF;
+  const beforeSha = process.env.GITHUB_EVENT_BEFORE;
+  const currentSha = process.env.GITHUB_SHA || "HEAD";
+
+  try {
+    if (baseRef) {
+      try {
+        execSync(`git fetch origin ${baseRef} --depth=1`, {
+          cwd: root,
+          stdio: "ignore",
+        });
+      } catch {
+        // The workflow may already have enough history.
+      }
+
+      return uniqueFiles(
+        execSync(`git diff --name-only origin/${baseRef}...HEAD`, {
+          cwd: root,
+          encoding: "utf8",
+        })
+          .split("\n")
+          .map((file) => file.trim())
+          .filter(Boolean)
+      );
+    }
+
+    if (beforeSha && currentSha) {
+      return uniqueFiles(
+        execSync(`git diff --name-only ${beforeSha} ${currentSha}`, {
+          cwd: root,
+          encoding: "utf8",
+        })
+          .split("\n")
+          .map((file) => file.trim())
+          .filter(Boolean)
+      );
+    }
+  } catch {
+    return [];
+  }
+
+  return [];
+}
+
+function uniqueFiles(files) {
+  return [...new Set(files)].sort();
+}
+
 function getCliVersion() {
   try {
     const currentFile = fileURLToPath(import.meta.url);