@crewhaus/rules-engine 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@crewhaus/rules-engine",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Cross-cutting (Track 10) — reads multi-language rule packs from rules/{common,typescript,python,...} and injects them as system-prompt prefixes. Source: ECC reference repo.",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/rules-engine"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/rules-engine#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,125 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadRules, renderRules, resolveProfile } from "./index";
+
+let projectRoot: string;
+
+beforeEach(() => {
+  projectRoot = mkdtempSync(join(tmpdir(), "rules-engine-test-"));
+});
+
+afterEach(() => {
+  rmSync(projectRoot, { recursive: true, force: true });
+});
+
+function seed(bucket: string, file: string, body: string): void {
+  const dir = join(projectRoot, "rules", bucket);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, file), body);
+}
+
+describe("loadRules", () => {
+  test("returns empty array when rules/ is missing", () => {
+    expect(loadRules({ projectRoot }).length).toBe(0);
+  });
+
+  test("returns common rules when no languages requested", () => {
+    seed("common", "always-be-kind.md", "Be kind.");
+    seed("typescript", "no-any.md", "Avoid any.");
+    const rules = loadRules({ projectRoot });
+    expect(rules.length).toBe(1);
+    expect(rules[0]?.id).toBe("always-be-kind");
+    expect(rules[0]?.bucket).toBe("common");
+  });
+
+  test("includes language buckets in standard profile (bucket-alphabetical order)", () => {
+    seed("common", "a.md", "x");
+    seed("typescript", "b.md", "x");
+    seed("python", "c.md", "x");
+    const rules = loadRules({
+      projectRoot,
+      languages: ["typescript", "python"],
+    });
+    // Buckets sort alphabetically: common, python, typescript.
+    const out = rules.map((r) => `${r.bucket}/${r.id}`);
+    expect(out).toEqual(["common/a", "python/c", "typescript/b"]);
+  });
+
+  test("ignores language buckets in core profile", () => {
+    seed("common", "a.md", "x");
+    seed("typescript", "b.md", "x");
+    const rules = loadRules({
+      projectRoot,
+      profile: "core",
+      languages: ["typescript"],
+    });
+    expect(rules.length).toBe(1);
+    expect(rules[0]?.bucket).toBe("common");
+  });
+
+  test("includes all present buckets in full profile", () => {
+    seed("common", "a.md", "x");
+    seed("typescript", "b.md", "x");
+    seed("rust", "c.md", "x");
+    const rules = loadRules({ projectRoot, profile: "full" });
+    expect(rules.length).toBe(3);
+  });
+
+  test("orders deterministically — bucket alphabetical, then file alphabetical", () => {
+    seed("python", "z.md", "x");
+    seed("python", "a.md", "x");
+    seed("common", "m.md", "x");
+    const rules = loadRules({ projectRoot, languages: ["python"] });
+    const ids = rules.map((r) => `${r.bucket}/${r.id}`);
+    expect(ids).toEqual(["common/m", "python/a", "python/z"]);
+  });
+
+  test("skips files that aren't .md or .txt", () => {
+    seed("common", "rule.md", "x");
+    seed("common", "ignore.json", "{}");
+    const rules = loadRules({ projectRoot });
+    expect(rules.length).toBe(1);
+  });
+});
+
+describe("renderRules", () => {
+  test("returns empty string for empty input", () => {
+    expect(renderRules([])).toBe("");
+  });
+
+  test("emits a section per bucket and a subsection per rule", () => {
+    seed("common", "a.md", "Body A");
+    seed("typescript", "b.md", "Body B");
+    const rendered = renderRules(loadRules({ projectRoot, languages: ["typescript"] }));
+    expect(rendered).toContain("# Project rules");
+    expect(rendered).toContain("## common");
+    expect(rendered).toContain("## typescript");
+    expect(rendered).toContain("### a");
+    expect(rendered).toContain("### b");
+    expect(rendered).toContain("Body A");
+    expect(rendered).toContain("Body B");
+  });
+
+  test("is byte-stable across calls (prompt-cache friendly)", () => {
+    seed("common", "a.md", "Body");
+    const rendered1 = renderRules(loadRules({ projectRoot }));
+    const rendered2 = renderRules(loadRules({ projectRoot }));
+    expect(rendered1).toBe(rendered2);
+  });
+});
+
+describe("resolveProfile", () => {
+  test("recognised values pass through", () => {
+    expect(resolveProfile("core")).toBe("core");
+    expect(resolveProfile("standard")).toBe("standard");
+    expect(resolveProfile("full")).toBe("full");
+  });
+
+  test("undefined and unrecognised default to standard", () => {
+    expect(resolveProfile(undefined)).toBe("standard");
+    expect(resolveProfile("unknown")).toBe("standard");
+    expect(resolveProfile("")).toBe("standard");
+  });
+});

package/src/index.ts

@@ -0,0 +1,146 @@
+/**
+ * Cross-cutting (Track 10) — `rules-engine`. Reads multi-language
+ * always-follow rule packs from `rules/{common,typescript,python,…}`
+ * and renders them as a system-prompt prefix.
+ *
+ * Source: ECC (https://github.com/affaan-m/ECC). ECC ships 12
+ * language ecosystems' worth of rule files, organized as a folder per
+ * language plus a `common/` folder for cross-language guidelines.
+ * Rules are *always-follow* (distinct from skills, which are
+ * workflow-triggered).
+ *
+ * The CrewHaus take:
+ *
+ *   - `rules/` is project-rooted. CrewHaus reads from `rules/common/`
+ *     and from `rules/<language>/` based on the spec's declared
+ *     language(s).
+ *   - Each file under `rules/<bucket>/` is one rule. The filename
+ *     (kebab-case) becomes the rule's `id`; the file body is the
+ *     rule text.
+ *   - The rules are concatenated with section headers and injected
+ *     into the agent's system prompt by callers (runtime-core's
+ *     prompt-builder).
+ *   - Empty/missing `rules/` directory is a no-op (graceful default).
+ *
+ * Also supports a `CREWHAUS_HOOK_PROFILE`-style env-var (here named
+ * `CREWHAUS_RULES_PROFILE`) to gate which buckets are included at
+ * runtime, e.g. `CREWHAUS_RULES_PROFILE=core` to limit to `common/`
+ * only.
+ *
+ * Reference repo: ECC (https://github.com/affaan-m/ECC).
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { CrewhausError } from "@crewhaus/errors";
+
+export class RulesEngineError extends CrewhausError {
+  override readonly name = "RulesEngineError";
+  constructor(message: string, cause?: unknown) {
+    super("config", message, cause);
+  }
+}
+
+export type Rule = {
+  readonly id: string;
+  readonly bucket: string;
+  readonly body: string;
+};
+
+export type LoadRulesOptions = {
+  /** Project root that contains the `rules/` directory. */
+  readonly projectRoot: string;
+  /** Languages to include (always merged with `common`). */
+  readonly languages?: ReadonlyArray<string>;
+  /**
+   * Override the profile env var read (`CREWHAUS_RULES_PROFILE`).
+   * `core` → common/ only. `standard` → common + named languages.
+   * `full` → every bucket present under `rules/`. Default: standard.
+   */
+  readonly profile?: "core" | "standard" | "full";
+};
+
+/**
+ * Load and order all rules per the profile + languages. Pure (no
+ * env read) — the CLI is responsible for resolving the env var.
+ *
+ * Returns rules in deterministic order (bucket alphabetical, then
+ * file alphabetical) so prompt-cache prefixes stay stable across runs.
+ */
+export function loadRules(opts: LoadRulesOptions): ReadonlyArray<Rule> {
+  const root = resolve(opts.projectRoot);
+  const rulesDir = join(root, "rules");
+  let buckets: string[];
+  try {
+    buckets = readdirSync(rulesDir).filter((name) => {
+      try {
+        return statSync(join(rulesDir, name)).isDirectory();
+      } catch {
+        return false;
+      }
+    });
+  } catch {
+    return [];
+  }
+  const profile = opts.profile ?? "standard";
+  const wanted = new Set<string>();
+  wanted.add("common");
+  if (profile === "standard") {
+    for (const lang of opts.languages ?? []) wanted.add(lang);
+  } else if (profile === "full") {
+    for (const b of buckets) wanted.add(b);
+  }
+  const selectedBuckets = buckets.filter((b) => wanted.has(b)).sort();
+
+  const out: Rule[] = [];
+  for (const bucket of selectedBuckets) {
+    const bucketDir = join(rulesDir, bucket);
+    let files: string[];
+    try {
+      files = readdirSync(bucketDir).filter((f) => f.endsWith(".md") || f.endsWith(".txt"));
+    } catch {
+      continue;
+    }
+    for (const file of files.sort()) {
+      const id = file.replace(/\.(md|txt)$/, "");
+      let body: string;
+      try {
+        body = readFileSync(join(bucketDir, file), "utf8");
+      } catch (err) {
+        throw new RulesEngineError(
+          `failed to read rule ${bucket}/${file}: ${(err as Error).message}`,
+        );
+      }
+      out.push({ id, bucket, body });
+    }
+  }
+  return out;
+}
+
+/**
+ * Render an ordered rule list as a markdown system-prompt prefix.
+ * Used by runtime-core to fold rules into the prompt during turn
+ * construction. Idempotent: identical input → identical output bytes,
+ * which preserves prompt-cache hits across turns.
+ */
+export function renderRules(rules: ReadonlyArray<Rule>): string {
+  if (rules.length === 0) return "";
+  const sections: string[] = ["# Project rules", ""];
+  let lastBucket: string | undefined;
+  for (const rule of rules) {
+    if (rule.bucket !== lastBucket) {
+      sections.push(`## ${rule.bucket}`, "");
+      lastBucket = rule.bucket;
+    }
+    sections.push(`### ${rule.id}`, "", rule.body.trim(), "");
+  }
+  return sections.join("\n");
+}
+
+/**
+ * Convenience env-var read for the CLI. Validates the profile
+ * value; falls back to `standard` for any unrecognised value.
+ */
+export function resolveProfile(envValue: string | undefined): "core" | "standard" | "full" {
+  if (envValue === "core" || envValue === "standard" || envValue === "full") return envValue;
+  return "standard";
+}