aioengine 0.1.3 → 0.1.4

package/README.md

@@ -25,6 +25,12 @@ 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
@@ -32,6 +38,7 @@ 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
 ```
 
@@ -39,7 +46,7 @@ npx aioengine rules
 
 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:
 
@@ -47,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
@@ -61,6 +70,12 @@ 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
@@ -122,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.
@@ -132,11 +193,20 @@ Run:
 npx aioengine rules
 ```
 
-This creates or skips:
+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 command creates or skips:
 
 ```txt
 CLAUDE.md
 .cursor/rules/aioengine.mdc
+.aioengine/suggested-claude-rules.md
 ```
 
 ## Example workflow
@@ -149,6 +219,7 @@ npx aioengine check
 
 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.3",
+  "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.")
@@ -275,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");
 
@@ -932,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);