@bpinternal/overwatch 0.1.0

package/dist/sensors/index.d.ts

@@ -0,0 +1,27 @@
+import type { RepoHandle } from "../repo-handle";
+import type { Signal } from "../types";
+/**
+ * A sensor that runs on the host but reads the repo through a {@link RepoHandle}
+ * proxying into the sandbox. Closures and imports work normally.
+ */
+export type SensorFn<TData = unknown> = (repo: RepoHandle) => Promise<Signal<TData>[]>;
+/**
+ * A sensor that is a standalone script uploaded into the sandbox and executed there
+ * with the repo root as cwd. Create one with `sensors.script`.
+ */
+export interface SensorScript<TData = unknown> {
+    kind: "sensor-script";
+    /** Path on the host to a script whose default export is `() => Promise<Signal[]>`. */
+    localPath: string;
+    /**
+     * Phantom marker for the `data` type the script's signals carry. A script runs in the
+     * sandbox, so its data type can't be inferred from the file — set it explicitly with
+     * `sensors.script<MyData>(path)` to type the paired actuator. Never populated at runtime.
+     */
+    readonly __data?: TData;
+}
+export type Sensor<TData = unknown> = SensorFn<TData> | SensorScript<TData>;
+export { script } from "./script";
+export { grep, type GrepOptions } from "./grep";
+export { astGrep, type AstGrepOptions, type AstGrepMatch } from "./ast-grep";
+export { reactDoctor, type ReactDoctorOptions, type ReactDoctorDiagnostic } from "./react-doctor";

package/dist/sensors/index.js

@@ -0,0 +1,38 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var sensors_exports = {};
+__export(sensors_exports, {
+  astGrep: () => import_ast_grep.astGrep,
+  grep: () => import_grep.grep,
+  reactDoctor: () => import_react_doctor.reactDoctor,
+  script: () => import_script.script
+});
+module.exports = __toCommonJS(sensors_exports);
+var import_script = require("./script");
+var import_grep = require("./grep");
+var import_ast_grep = require("./ast-grep");
+var import_react_doctor = require("./react-doctor");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  astGrep,
+  grep,
+  reactDoctor,
+  script
+});
+//# sourceMappingURL=index.js.map

package/dist/sensors/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/sensors/index.ts"],
+  "sourcesContent": ["import type { RepoHandle } from \"../repo-handle\";\nimport type { Signal } from \"../types\";\n\n/**\n * A sensor that runs on the host but reads the repo through a {@link RepoHandle}\n * proxying into the sandbox. Closures and imports work normally.\n */\nexport type SensorFn<TData = unknown> = (repo: RepoHandle) => Promise<Signal<TData>[]>;\n\n/**\n * A sensor that is a standalone script uploaded into the sandbox and executed there\n * with the repo root as cwd. Create one with `sensors.script`.\n */\nexport interface SensorScript<TData = unknown> {\n  kind: \"sensor-script\";\n  /** Path on the host to a script whose default export is `() => Promise<Signal[]>`. */\n  localPath: string;\n  /**\n   * Phantom marker for the `data` type the script's signals carry. A script runs in the\n   * sandbox, so its data type can't be inferred from the file \u2014 set it explicitly with\n   * `sensors.script<MyData>(path)` to type the paired actuator. Never populated at runtime.\n   */\n  readonly __data?: TData;\n}\n\nexport type Sensor<TData = unknown> = SensorFn<TData> | SensorScript<TData>;\n\nexport { script } from \"./script\";\nexport { grep, type GrepOptions } from \"./grep\";\nexport { astGrep, type AstGrepOptions, type AstGrepMatch } from \"./ast-grep\";\nexport { reactDoctor, type ReactDoctorOptions, type ReactDoctorDiagnostic } from \"./react-doctor\";\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA2BA,oBAAuB;AACvB,kBAAuC;AACvC,sBAAgE;AAChE,0BAAiF;",
+  "names": []
+}

package/dist/sensors/react-doctor.d.ts

@@ -0,0 +1,43 @@
+import type { SensorFn } from "./index";
+/** One react-doctor finding, as emitted by `react-doctor --json`. */
+export interface ReactDoctorDiagnostic {
+    filePath: string;
+    plugin: string;
+    rule: string;
+    severity: string;
+    title?: string;
+    message: string;
+    help?: string;
+    /** 1-based; 0 means the finding is file-level. */
+    line: number;
+    column?: number;
+    category?: string;
+}
+export interface ReactDoctorOptions {
+    /**
+     * Directory (relative to the repo root) to scan. Required — scoping the scan keeps
+     * the signal set intentional; pass "." to explicitly scan the whole repo.
+     */
+    path: string;
+    /** Only report these categories (e.g. ["Performance", "Bugs"]). Default: all. */
+    categories?: string[];
+    /**
+     * Builds the signal message for a diagnostic. Signals are matched across runs by
+     * file + message, so keep it stable for a given anomaly. The default combines the
+     * rule with react-doctor's message.
+     */
+    message?: (diagnostic: ReactDoctorDiagnostic) => string;
+}
+/**
+ * Sensor that runs [react-doctor](https://react.doctor) inside the sandbox and turns
+ * every diagnostic into a signal. Severity maps to priority (error -> high,
+ * warning -> medium, else low); the full diagnostic (including react-doctor's `help`
+ * text, useful in an actuator's instructions) rides along in `data`.
+ *
+ * @example
+ * sensor: sensors.reactDoctor({
+ *   path: "packages/frontend",
+ *   categories: ["Performance", "Bugs"],
+ * })
+ */
+export declare const reactDoctor: (options: ReactDoctorOptions) => SensorFn<ReactDoctorDiagnostic>;

package/dist/sensors/react-doctor.js

@@ -0,0 +1,71 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var react_doctor_exports = {};
+__export(react_doctor_exports, {
+  reactDoctor: () => reactDoctor
+});
+module.exports = __toCommonJS(react_doctor_exports);
+const reactDoctor = (options) => {
+  return async (repo) => {
+    const output = "/tmp/react-doctor.json";
+    const categories = (options.categories ?? []).map((category) => ` --category ${shellQuote(category)}`).join("");
+    const run = await repo.exec(
+      `bunx -y react-doctor@latest ${shellQuote(options.path)} --json --no-analytics${categories} > ${output} 2>/dev/null; cat ${output}`,
+      { timeoutSec: 900 }
+    );
+    let report;
+    try {
+      report = JSON.parse(run.output);
+    } catch {
+      throw new Error(`react-doctor produced unparseable output: ${run.output.slice(0, 500)}`);
+    }
+    if (!report.ok) {
+      throw new Error(`react-doctor failed: ${run.output.slice(0, 500)}`);
+    }
+    return (report.projects ?? []).flatMap((project) => {
+      const projectRelative = project.directory.slice(report.directory.length);
+      const prefix = joinPaths(options.path, projectRelative);
+      return (project.diagnostics ?? []).map((diagnostic) => ({
+        location: {
+          file: joinPaths(prefix, diagnostic.filePath),
+          line: diagnostic.line > 0 ? diagnostic.line : void 0
+        },
+        message: options.message?.(diagnostic) ?? `react-doctor ${diagnostic.rule}: ${diagnostic.message}`,
+        priority: reactDoctorPriority(diagnostic.severity),
+        data: diagnostic
+      }));
+    });
+  };
+};
+function reactDoctorPriority(severity) {
+  if (severity === "error") return "high";
+  if (severity === "warning") return "medium";
+  return "low";
+}
+function joinPaths(...parts) {
+  return parts.map((part) => part.replace(/^[./]+|\/+$/g, "")).filter((part) => part !== "").join("/");
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  reactDoctor
+});
+//# sourceMappingURL=react-doctor.js.map

package/dist/sensors/react-doctor.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/sensors/react-doctor.ts"],
+  "sourcesContent": ["import type { SignalPriority } from \"../types\";\nimport type { SensorFn } from \"./index\";\n\n/** One react-doctor finding, as emitted by `react-doctor --json`. */\nexport interface ReactDoctorDiagnostic {\n  filePath: string;\n  plugin: string;\n  rule: string;\n  severity: string;\n  title?: string;\n  message: string;\n  help?: string;\n  /** 1-based; 0 means the finding is file-level. */\n  line: number;\n  column?: number;\n  category?: string;\n}\n\nexport interface ReactDoctorOptions {\n  /**\n   * Directory (relative to the repo root) to scan. Required \u2014 scoping the scan keeps\n   * the signal set intentional; pass \".\" to explicitly scan the whole repo.\n   */\n  path: string;\n  /** Only report these categories (e.g. [\"Performance\", \"Bugs\"]). Default: all. */\n  categories?: string[];\n  /**\n   * Builds the signal message for a diagnostic. Signals are matched across runs by\n   * file + message, so keep it stable for a given anomaly. The default combines the\n   * rule with react-doctor's message.\n   */\n  message?: (diagnostic: ReactDoctorDiagnostic) => string;\n}\n\n/**\n * Sensor that runs [react-doctor](https://react.doctor) inside the sandbox and turns\n * every diagnostic into a signal. Severity maps to priority (error -> high,\n * warning -> medium, else low); the full diagnostic (including react-doctor's `help`\n * text, useful in an actuator's instructions) rides along in `data`.\n *\n * @example\n * sensor: sensors.reactDoctor({\n *   path: \"packages/frontend\",\n *   categories: [\"Performance\", \"Bugs\"],\n * })\n */\nexport const reactDoctor = (options: ReactDoctorOptions): SensorFn<ReactDoctorDiagnostic> => {\n  return async (repo) => {\n    const output = \"/tmp/react-doctor.json\";\n    const categories = (options.categories ?? [])\n      .map((category) => ` --category ${shellQuote(category)}`)\n      .join(\"\");\n    // react-doctor exits 1 whenever it finds issues, so success is judged from the\n    // JSON (`ok`), not the exit code. stdout goes through a file to keep it parseable\n    // even if bunx prints installation noise.\n    const run = await repo.exec(\n      `bunx -y react-doctor@latest ${shellQuote(options.path)} --json --no-analytics${categories} > ${output} 2>/dev/null; cat ${output}`,\n      { timeoutSec: 900 },\n    );\n\n    type Report = {\n      ok: boolean;\n      directory: string;\n      projects?: Array<{ directory: string; diagnostics?: ReactDoctorDiagnostic[] }>;\n    };\n    let report: Report;\n    try {\n      report = JSON.parse(run.output) as Report;\n    } catch {\n      throw new Error(`react-doctor produced unparseable output: ${run.output.slice(0, 500)}`);\n    }\n    if (!report.ok) {\n      throw new Error(`react-doctor failed: ${run.output.slice(0, 500)}`);\n    }\n\n    return (report.projects ?? []).flatMap((project) => {\n      // filePath is relative to the project directory; rebuild a repo-relative path\n      // (scan path + project dir within the scan root + filePath) for the signal's file.\n      const projectRelative = project.directory.slice(report.directory.length);\n      const prefix = joinPaths(options.path, projectRelative);\n      return (project.diagnostics ?? []).map((diagnostic) => ({\n        location: {\n          file: joinPaths(prefix, diagnostic.filePath),\n          line: diagnostic.line > 0 ? diagnostic.line : undefined,\n        },\n        message:\n          options.message?.(diagnostic) ??\n          `react-doctor ${diagnostic.rule}: ${diagnostic.message}`,\n        priority: reactDoctorPriority(diagnostic.severity),\n        data: diagnostic,\n      }));\n    });\n  };\n};\n\nfunction reactDoctorPriority(severity: string): SignalPriority {\n  if (severity === \"error\") return \"high\";\n  if (severity === \"warning\") return \"medium\";\n  return \"low\";\n}\n\nfunction joinPaths(...parts: string[]): string {\n  return parts\n    .map((part) => part.replace(/^[./]+|\\/+$/g, \"\"))\n    .filter((part) => part !== \"\")\n    .join(\"/\");\n}\n\n/** Single-quote for the shell; category names and paths are arbitrary user text. */\nfunction shellQuote(value: string): string {\n  return `'${value.replace(/'/g, `'\\\\''`)}'`;\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA8CO,MAAM,cAAc,CAAC,YAAiE;AAC3F,SAAO,OAAO,SAAS;AACrB,UAAM,SAAS;AACf,UAAM,cAAc,QAAQ,cAAc,CAAC,GACxC,IAAI,CAAC,aAAa,eAAe,WAAW,QAAQ,CAAC,EAAE,EACvD,KAAK,EAAE;AAIV,UAAM,MAAM,MAAM,KAAK;AAAA,MACrB,+BAA+B,WAAW,QAAQ,IAAI,CAAC,yBAAyB,UAAU,MAAM,MAAM,qBAAqB,MAAM;AAAA,MACjI,EAAE,YAAY,IAAI;AAAA,IACpB;AAOA,QAAI;AACJ,QAAI;AACF,eAAS,KAAK,MAAM,IAAI,MAAM;AAAA,IAChC,QAAQ;AACN,YAAM,IAAI,MAAM,6CAA6C,IAAI,OAAO,MAAM,GAAG,GAAG,CAAC,EAAE;AAAA,IACzF;AACA,QAAI,CAAC,OAAO,IAAI;AACd,YAAM,IAAI,MAAM,wBAAwB,IAAI,OAAO,MAAM,GAAG,GAAG,CAAC,EAAE;AAAA,IACpE;AAEA,YAAQ,OAAO,YAAY,CAAC,GAAG,QAAQ,CAAC,YAAY;AAGlD,YAAM,kBAAkB,QAAQ,UAAU,MAAM,OAAO,UAAU,MAAM;AACvE,YAAM,SAAS,UAAU,QAAQ,MAAM,eAAe;AACtD,cAAQ,QAAQ,eAAe,CAAC,GAAG,IAAI,CAAC,gBAAgB;AAAA,QACtD,UAAU;AAAA,UACR,MAAM,UAAU,QAAQ,WAAW,QAAQ;AAAA,UAC3C,MAAM,WAAW,OAAO,IAAI,WAAW,OAAO;AAAA,QAChD;AAAA,QACA,SACE,QAAQ,UAAU,UAAU,KAC5B,gBAAgB,WAAW,IAAI,KAAK,WAAW,OAAO;AAAA,QACxD,UAAU,oBAAoB,WAAW,QAAQ;AAAA,QACjD,MAAM;AAAA,MACR,EAAE;AAAA,IACJ,CAAC;AAAA,EACH;AACF;AAEA,SAAS,oBAAoB,UAAkC;AAC7D,MAAI,aAAa,QAAS,QAAO;AACjC,MAAI,aAAa,UAAW,QAAO;AACnC,SAAO;AACT;AAEA,SAAS,aAAa,OAAyB;AAC7C,SAAO,MACJ,IAAI,CAAC,SAAS,KAAK,QAAQ,gBAAgB,EAAE,CAAC,EAC9C,OAAO,CAAC,SAAS,SAAS,EAAE,EAC5B,KAAK,GAAG;AACb;AAGA,SAAS,WAAW,OAAuB;AACzC,SAAO,IAAI,MAAM,QAAQ,MAAM,OAAO,CAAC;AACzC;",
+  "names": []
+}

package/dist/sensors/script.d.ts

@@ -0,0 +1,7 @@
+import type { SensorScript } from "./index";
+/**
+ * Sensor that is a standalone local script uploaded into the sandbox and executed
+ * there with the repo root as cwd. The file's default export must be
+ * `() => Promise<Signal[]>`.
+ */
+export declare const script: <TData = unknown>(localPath: string) => SensorScript<TData>;

package/dist/sensors/script.js

@@ -0,0 +1,32 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var script_exports = {};
+__export(script_exports, {
+  script: () => script
+});
+module.exports = __toCommonJS(script_exports);
+const script = (localPath) => ({
+  kind: "sensor-script",
+  localPath
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  script
+});
+//# sourceMappingURL=script.js.map

package/dist/sensors/script.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/sensors/script.ts"],
+  "sourcesContent": ["import type { SensorScript } from \"./index\";\n\n/**\n * Sensor that is a standalone local script uploaded into the sandbox and executed\n * there with the repo root as cwd. The file's default export must be\n * `() => Promise<Signal[]>`.\n */\nexport const script = <TData = unknown>(localPath: string): SensorScript<TData> => ({\n  kind: \"sensor-script\",\n  localPath,\n});\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAOO,MAAM,SAAS,CAAkB,eAA4C;AAAA,EAClF,MAAM;AAAA,EACN;AACF;",
+  "names": []
+}

package/dist/sensors.d.ts

@@ -0,0 +1,117 @@
+import type { GrepMatch } from "./repo-handle";
+import type { SensorFn, SensorScript, SignalPriority } from "./types";
+/**
+ * Sensor that is a standalone local script uploaded into the sandbox and executed
+ * there with the repo root as cwd. The file's default export must be
+ * `() => Promise<Signal[]>`.
+ */
+export declare const script: <TData = unknown>(localPath: string) => SensorScript<TData>;
+export interface GrepOptions {
+    /** Text/regex pattern searched in file contents. */
+    pattern: string;
+    /**
+     * Paths (relative to the repo root) to search. Required — scoping the search keeps
+     * the signal set intentional; pass ["."] to explicitly search the whole repo.
+     */
+    paths: string[];
+    /** Applied to every signal. Default "medium". */
+    priority?: SignalPriority;
+    /**
+     * Builds the signal message for a match. Signals are matched across runs by
+     * file + message, so keep it stable for a given anomaly. The default includes the
+     * matched line, which naturally disappears once the anomaly is fixed.
+     */
+    message?: (match: GrepMatch) => string;
+}
+/**
+ * Sensor that searches file contents and turns every matching line into a signal.
+ *
+ * @example
+ * sensor: sensors.grep({
+ *   pattern: "TODO:",
+ *   paths: ["src/"],
+ *   message: (match) => `unresolved TODO: ${match.content.trim()}`,
+ * })
+ */
+export declare const grep: (options: GrepOptions) => SensorFn<GrepMatch>;
+/** One react-doctor finding, as emitted by `react-doctor --json`. */
+export interface ReactDoctorDiagnostic {
+    filePath: string;
+    plugin: string;
+    rule: string;
+    severity: string;
+    title?: string;
+    message: string;
+    help?: string;
+    /** 1-based; 0 means the finding is file-level. */
+    line: number;
+    column?: number;
+    category?: string;
+}
+export interface ReactDoctorOptions {
+    /**
+     * Directory (relative to the repo root) to scan. Required — scoping the scan keeps
+     * the signal set intentional; pass "." to explicitly scan the whole repo.
+     */
+    path: string;
+    /** Only report these categories (e.g. ["Performance", "Bugs"]). Default: all. */
+    categories?: string[];
+    /**
+     * Builds the signal message for a diagnostic. Signals are matched across runs by
+     * file + message, so keep it stable for a given anomaly. The default combines the
+     * rule with react-doctor's message.
+     */
+    message?: (diagnostic: ReactDoctorDiagnostic) => string;
+}
+/**
+ * Sensor that runs [react-doctor](https://react.doctor) inside the sandbox and turns
+ * every diagnostic into a signal. Severity maps to priority (error -> high,
+ * warning -> medium, else low); the full diagnostic (including react-doctor's `help`
+ * text, useful in an actuator's instructions) rides along in `data`.
+ *
+ * @example
+ * sensor: sensors.reactDoctor({
+ *   path: "packages/frontend",
+ *   categories: ["Performance", "Bugs"],
+ * })
+ */
+export declare const reactDoctor: (options: ReactDoctorOptions) => SensorFn<ReactDoctorDiagnostic>;
+export interface AstGrepMatch {
+    file: string;
+    /** 1-based, like Signal.location.line. */
+    line: number;
+    /** Source text of the matched node. */
+    text: string;
+}
+export interface AstGrepOptions {
+    /** ast-grep pattern, e.g. "console.log($$$ARGS)". */
+    pattern: string;
+    /** Language to parse, e.g. "typescript" or "tsx". Omit to let ast-grep infer it per file. */
+    language?: string;
+    /** Applied to every signal. Default "medium". */
+    priority?: SignalPriority;
+    /**
+     * Builds the signal message for a match. Signals are matched across runs by
+     * file + message, so keep it stable for a given anomaly. The default includes the
+     * matched text, which naturally disappears once the anomaly is fixed.
+     */
+    message?: (match: AstGrepMatch) => string;
+    /**
+     * Paths (relative to the repo root) to scan. Required — scoping the scan keeps the
+     * signal set intentional; pass ["."] to explicitly scan the whole repo.
+     */
+    paths: string[];
+}
+/**
+ * Sensor that runs [ast-grep](https://ast-grep.github.io) inside the sandbox and turns
+ * every structural match into a signal. The CLI is installed on first use if the
+ * sandbox image doesn't have it (pre-bake `@ast-grep/cli` in a snapshot to skip that).
+ *
+ * @example
+ * sensor: sensors.astGrep({
+ *   pattern: "throw new Error($$$)",
+ *   language: "ts",
+ *   paths: ["packages/backend/src/trpc/routers/"],
+ * })
+ */
+export declare const astGrep: (options: AstGrepOptions) => SensorFn<AstGrepMatch>;

package/dist/sensors.js

@@ -0,0 +1,126 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var sensors_exports = {};
+__export(sensors_exports, {
+  astGrep: () => astGrep,
+  grep: () => grep,
+  reactDoctor: () => reactDoctor,
+  script: () => script
+});
+module.exports = __toCommonJS(sensors_exports);
+const script = (localPath) => ({
+  kind: "sensor-script",
+  localPath
+});
+const grep = (options) => {
+  return async (repo) => {
+    const matches = await repo.grep(options.pattern, options.paths);
+    return matches.map((match) => ({
+      location: { file: match.file, line: match.line },
+      message: options.message?.(match) ?? `matches "${options.pattern}": ${match.content.trim().slice(0, 120)}`,
+      priority: options.priority ?? "medium",
+      data: match
+    }));
+  };
+};
+const reactDoctor = (options) => {
+  return async (repo) => {
+    const output = "/tmp/react-doctor.json";
+    const categories = (options.categories ?? []).map((category) => ` --category ${shellQuote(category)}`).join("");
+    const run = await repo.exec(
+      `bunx -y react-doctor@latest ${shellQuote(options.path)} --json --no-analytics${categories} > ${output} 2>/dev/null; cat ${output}`,
+      { timeoutSec: 900 }
+    );
+    let report;
+    try {
+      report = JSON.parse(run.output);
+    } catch {
+      throw new Error(`react-doctor produced unparseable output: ${run.output.slice(0, 500)}`);
+    }
+    if (!report.ok) {
+      throw new Error(`react-doctor failed: ${run.output.slice(0, 500)}`);
+    }
+    return (report.projects ?? []).flatMap((project) => {
+      const projectRelative = project.directory.slice(report.directory.length);
+      const prefix = joinPaths(options.path, projectRelative);
+      return (project.diagnostics ?? []).map((diagnostic) => ({
+        location: {
+          file: joinPaths(prefix, diagnostic.filePath),
+          line: diagnostic.line > 0 ? diagnostic.line : void 0
+        },
+        message: options.message?.(diagnostic) ?? `react-doctor ${diagnostic.rule}: ${diagnostic.message}`,
+        priority: reactDoctorPriority(diagnostic.severity),
+        data: diagnostic
+      }));
+    });
+  };
+};
+function reactDoctorPriority(severity) {
+  if (severity === "error") return "high";
+  if (severity === "warning") return "medium";
+  return "low";
+}
+function joinPaths(...parts) {
+  return parts.map((part) => part.replace(/^[./]+|\/+$/g, "")).filter((part) => part !== "").join("/");
+}
+const astGrep = (options) => {
+  return async (repo) => {
+    const install = await repo.exec("command -v ast-grep || npm install -g @ast-grep/cli", { timeoutSec: 600 });
+    if (install.exitCode !== 0) {
+      throw new Error(`failed to install ast-grep: ${install.output}`);
+    }
+    const lang = options.language ? ` --lang ${options.language}` : "";
+    const paths = ` ${options.paths.map(shellQuote).join(" ")}`;
+    const run = await repo.exec(`ast-grep run --pattern ${shellQuote(options.pattern)}${lang} --json${paths}`, {
+      timeoutSec: 600
+    });
+    if (run.exitCode !== 0) {
+      throw new Error(`ast-grep exited ${run.exitCode}: ${run.output}`);
+    }
+    const results = JSON.parse(run.output);
+    return results.map((result) => {
+      const match = {
+        file: result.file,
+        line: result.range.start.line + 1,
+        text: result.text
+      };
+      return {
+        location: { file: match.file, line: match.line },
+        message: options.message?.(match) ?? defaultMessage(options.pattern, match),
+        priority: options.priority ?? "medium",
+        data: match
+      };
+    });
+  };
+};
+function defaultMessage(pattern, match) {
+  const text = match.text.split("\n")[0].slice(0, 120);
+  return `matches pattern "${pattern}": ${text}`;
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  astGrep,
+  grep,
+  reactDoctor,
+  script
+});
+//# sourceMappingURL=sensors.js.map

package/dist/sensors.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/sensors.ts"],
+  "sourcesContent": ["import type { GrepMatch } from \"./repo-handle\";\nimport type { SensorFn, SensorScript, SignalPriority } from \"./types\";\n\n/**\n * Sensor that is a standalone local script uploaded into the sandbox and executed\n * there with the repo root as cwd. The file's default export must be\n * `() => Promise<Signal[]>`.\n */\nexport const script = <TData = unknown>(localPath: string): SensorScript<TData> => ({\n  kind: \"sensor-script\",\n  localPath,\n});\n\nexport interface GrepOptions {\n  /** Text/regex pattern searched in file contents. */\n  pattern: string;\n  /**\n   * Paths (relative to the repo root) to search. Required \u2014 scoping the search keeps\n   * the signal set intentional; pass [\".\"] to explicitly search the whole repo.\n   */\n  paths: string[];\n  /** Applied to every signal. Default \"medium\". */\n  priority?: SignalPriority;\n  /**\n   * Builds the signal message for a match. Signals are matched across runs by\n   * file + message, so keep it stable for a given anomaly. The default includes the\n   * matched line, which naturally disappears once the anomaly is fixed.\n   */\n  message?: (match: GrepMatch) => string;\n}\n\n/**\n * Sensor that searches file contents and turns every matching line into a signal.\n *\n * @example\n * sensor: sensors.grep({\n *   pattern: \"TODO:\",\n *   paths: [\"src/\"],\n *   message: (match) => `unresolved TODO: ${match.content.trim()}`,\n * })\n */\nexport const grep = (options: GrepOptions): SensorFn<GrepMatch> => {\n  return async (repo) => {\n    const matches = await repo.grep(options.pattern, options.paths);\n    return matches.map((match) => ({\n      location: { file: match.file, line: match.line },\n      message: options.message?.(match) ?? `matches \"${options.pattern}\": ${match.content.trim().slice(0, 120)}`,\n      priority: options.priority ?? \"medium\",\n      data: match,\n    }));\n  };\n};\n\n/** One react-doctor finding, as emitted by `react-doctor --json`. */\nexport interface ReactDoctorDiagnostic {\n  filePath: string;\n  plugin: string;\n  rule: string;\n  severity: string;\n  title?: string;\n  message: string;\n  help?: string;\n  /** 1-based; 0 means the finding is file-level. */\n  line: number;\n  column?: number;\n  category?: string;\n}\n\nexport interface ReactDoctorOptions {\n  /**\n   * Directory (relative to the repo root) to scan. Required \u2014 scoping the scan keeps\n   * the signal set intentional; pass \".\" to explicitly scan the whole repo.\n   */\n  path: string;\n  /** Only report these categories (e.g. [\"Performance\", \"Bugs\"]). Default: all. */\n  categories?: string[];\n  /**\n   * Builds the signal message for a diagnostic. Signals are matched across runs by\n   * file + message, so keep it stable for a given anomaly. The default combines the\n   * rule with react-doctor's message.\n   */\n  message?: (diagnostic: ReactDoctorDiagnostic) => string;\n}\n\n/**\n * Sensor that runs [react-doctor](https://react.doctor) inside the sandbox and turns\n * every diagnostic into a signal. Severity maps to priority (error -> high,\n * warning -> medium, else low); the full diagnostic (including react-doctor's `help`\n * text, useful in an actuator's instructions) rides along in `data`.\n *\n * @example\n * sensor: sensors.reactDoctor({\n *   path: \"packages/frontend\",\n *   categories: [\"Performance\", \"Bugs\"],\n * })\n */\nexport const reactDoctor = (options: ReactDoctorOptions): SensorFn<ReactDoctorDiagnostic> => {\n  return async (repo) => {\n    const output = \"/tmp/react-doctor.json\";\n    const categories = (options.categories ?? [])\n      .map((category) => ` --category ${shellQuote(category)}`)\n      .join(\"\");\n    // react-doctor exits 1 whenever it finds issues, so success is judged from the\n    // JSON (`ok`), not the exit code. stdout goes through a file to keep it parseable\n    // even if bunx prints installation noise.\n    const run = await repo.exec(\n      `bunx -y react-doctor@latest ${shellQuote(options.path)} --json --no-analytics${categories} > ${output} 2>/dev/null; cat ${output}`,\n      { timeoutSec: 900 },\n    );\n\n    type Report = {\n      ok: boolean;\n      directory: string;\n      projects?: Array<{ directory: string; diagnostics?: ReactDoctorDiagnostic[] }>;\n    };\n    let report: Report;\n    try {\n      report = JSON.parse(run.output) as Report;\n    } catch {\n      throw new Error(`react-doctor produced unparseable output: ${run.output.slice(0, 500)}`);\n    }\n    if (!report.ok) {\n      throw new Error(`react-doctor failed: ${run.output.slice(0, 500)}`);\n    }\n\n    return (report.projects ?? []).flatMap((project) => {\n      // filePath is relative to the project directory; rebuild a repo-relative path\n      // (scan path + project dir within the scan root + filePath) for the signal's file.\n      const projectRelative = project.directory.slice(report.directory.length);\n      const prefix = joinPaths(options.path, projectRelative);\n      return (project.diagnostics ?? []).map((diagnostic) => ({\n        location: {\n          file: joinPaths(prefix, diagnostic.filePath),\n          line: diagnostic.line > 0 ? diagnostic.line : undefined,\n        },\n        message:\n          options.message?.(diagnostic) ??\n          `react-doctor ${diagnostic.rule}: ${diagnostic.message}`,\n        priority: reactDoctorPriority(diagnostic.severity),\n        data: diagnostic,\n      }));\n    });\n  };\n};\n\nfunction reactDoctorPriority(severity: string): SignalPriority {\n  if (severity === \"error\") return \"high\";\n  if (severity === \"warning\") return \"medium\";\n  return \"low\";\n}\n\nfunction joinPaths(...parts: string[]): string {\n  return parts\n    .map((part) => part.replace(/^[./]+|\\/+$/g, \"\"))\n    .filter((part) => part !== \"\")\n    .join(\"/\");\n}\n\nexport interface AstGrepMatch {\n  file: string;\n  /** 1-based, like Signal.location.line. */\n  line: number;\n  /** Source text of the matched node. */\n  text: string;\n}\n\nexport interface AstGrepOptions {\n  /** ast-grep pattern, e.g. \"console.log($$$ARGS)\". */\n  pattern: string;\n  /** Language to parse, e.g. \"typescript\" or \"tsx\". Omit to let ast-grep infer it per file. */\n  language?: string;\n  /** Applied to every signal. Default \"medium\". */\n  priority?: SignalPriority;\n  /**\n   * Builds the signal message for a match. Signals are matched across runs by\n   * file + message, so keep it stable for a given anomaly. The default includes the\n   * matched text, which naturally disappears once the anomaly is fixed.\n   */\n  message?: (match: AstGrepMatch) => string;\n  /**\n   * Paths (relative to the repo root) to scan. Required \u2014 scoping the scan keeps the\n   * signal set intentional; pass [\".\"] to explicitly scan the whole repo.\n   */\n  paths: string[];\n}\n\n/**\n * Sensor that runs [ast-grep](https://ast-grep.github.io) inside the sandbox and turns\n * every structural match into a signal. The CLI is installed on first use if the\n * sandbox image doesn't have it (pre-bake `@ast-grep/cli` in a snapshot to skip that).\n *\n * @example\n * sensor: sensors.astGrep({\n *   pattern: \"throw new Error($$$)\",\n *   language: \"ts\",\n *   paths: [\"packages/backend/src/trpc/routers/\"],\n * })\n */\nexport const astGrep = (options: AstGrepOptions): SensorFn<AstGrepMatch> => {\n  return async (repo) => {\n    const install = await repo.exec(\"command -v ast-grep || npm install -g @ast-grep/cli\", { timeoutSec: 600 });\n    if (install.exitCode !== 0) {\n      throw new Error(`failed to install ast-grep: ${install.output}`);\n    }\n\n    const lang = options.language ? ` --lang ${options.language}` : \"\";\n    const paths = ` ${options.paths.map(shellQuote).join(\" \")}`;\n    const run = await repo.exec(`ast-grep run --pattern ${shellQuote(options.pattern)}${lang} --json${paths}`, {\n      timeoutSec: 600,\n    });\n    if (run.exitCode !== 0) {\n      throw new Error(`ast-grep exited ${run.exitCode}: ${run.output}`);\n    }\n\n    const results = JSON.parse(run.output) as Array<{\n      file: string;\n      text: string;\n      range: { start: { line: number } };\n    }>;\n\n    return results.map((result) => {\n      const match: AstGrepMatch = {\n        file: result.file,\n        line: result.range.start.line + 1,\n        text: result.text,\n      };\n      return {\n        location: { file: match.file, line: match.line },\n        message: options.message?.(match) ?? defaultMessage(options.pattern, match),\n        priority: options.priority ?? \"medium\",\n        data: match,\n      };\n    });\n  };\n};\n\nfunction defaultMessage(pattern: string, match: AstGrepMatch): string {\n  const text = match.text.split(\"\\n\")[0]!.slice(0, 120);\n  return `matches pattern \"${pattern}\": ${text}`;\n}\n\n/** Single-quote for the shell \u2014 ast-grep patterns are full of `$VAR`s the shell must not expand. */\nfunction shellQuote(value: string): string {\n  return `'${value.replace(/'/g, `'\\\\''`)}'`;\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/types.d.ts

@@ -0,0 +1,119 @@
+import type { Agent } from "./agents";
+import type { Actuator, CommentActuator } from "./actuators";
+import type { Sensor } from "./sensors";
+import type { Picker } from "./pickers";
+import type { GitSource, PrComment } from "./github";
+export type SignalPriority = "low" | "medium" | "high";
+/**
+ * An anomaly detected by the sensor.
+ *
+ * Identity note: after a fix, line numbers shift, so a signal is considered "the same"
+ * across sensor runs when its `location.file` and `message` match — `location.line` is
+ * informational only. Keep `message` stable for a given anomaly (don't embed line numbers
+ * or timestamps in it).
+ */
+export interface Signal<TData = unknown> {
+    /**
+     * Where the anomaly lives. Optional — some anomalies are repo-wide or not tied to a
+     * single place. When present, `file` anchors the signal's identity (see note above).
+     */
+    location?: {
+        file: string;
+        line?: number;
+    };
+    message: string;
+    /** Optional; treated as unset (rather than a default) wherever no priority is given. */
+    priority?: SignalPriority;
+    /**
+     * Anything the sensor wants to carry through to the picker and actuator untouched.
+     * `TData` is inferred from the sensor, so an actuator paired with it sees this exact
+     * type on `signal.data` (see {@link ControlLoopOptions}).
+     */
+    data?: TData;
+}
+/**
+ * Constructor argument of ControlLoop: identity and static settings, behavior alongside them.
+ *
+ * `TData` is inferred from the `sensor` and flows to the `picker` and `actuator`, so the
+ * `data` a sensor attaches to its signals reaches the actuator with the same static type.
+ */
+export interface ControlLoopOptions<TData = unknown> {
+    /**
+     * Human-readable name of the loop. Its slug (e.g. "My Loop" -> "my-loop") is applied
+     * as a label on every PR the loop opens, and is what `config.maxOpenPrCount` counts
+     * against.
+     */
+    label: string;
+    config: ControlLoopConfig;
+    sensor: Sensor<TData>;
+    /** Defaults to `pickers.count(1)`. */
+    picker?: Picker<TData>;
+    actuator: Actuator<TData>;
+    /** Customizes the instructions built from PR comments in `applyPrComments`. */
+    commentActuator?: CommentActuator;
+}
+export interface ControlLoopConfig {
+    /** Skip the run entirely if this many PRs with the loop's label are already open. */
+    maxOpenPrCount?: number;
+    /**
+     * Prefix of the branches the loop pushes, e.g. "bots/cleanup" ->
+     * "bots/cleanup/<label-slug>-<run-id>". Default "control-loop".
+     */
+    branchPrefix?: string;
+    git: GitSource;
+    agent: Agent;
+    /** Shell commands the loop runs inside the sandbox, all from the repo root. */
+    hooks?: {
+        /**
+         * Run right after cloning, before the sensor and agent (e.g. "bun install" to set
+         * up dependencies). The run aborts if it exits non-zero.
+         */
+        setup?: string;
+        /**
+         * Run after the agent finishes and before committing — typically the repo's
+         * auto-fix formatter (e.g. "bun run fix:format"). It normalizes everything the
+         * loop commits (agent edits and lib-generated files alike) so the PR passes repo
+         * formatting checks. The run aborts if it exits non-zero.
+         */
+        preCommit?: string;
+    };
+    /** Environment variables set on the sandbox at creation. */
+    env?: Record<string, string>;
+    /** Max agent attempts per signal before the run is declared failed. Default 3. */
+    maxFixAttempts?: number;
+    sandbox?: {
+        /**
+         * Daytona snapshot to create the sandbox from. Pre-bake your toolchain and the
+         * agent's CLI into it to skip per-run installs. Defaults to Daytona's typescript
+         * sandbox, with the agent CLI installed at run start.
+         */
+        snapshot?: string;
+    };
+}
+export type ControlLoopRunResult<TData = unknown> = {
+    status: "skipped";
+    reason: string;
+} | {
+    status: "clean";
+} | {
+    status: "fix-failed";
+    unresolved: Signal<TData>[];
+} | {
+    status: "pr-opened";
+    prUrl: string;
+    fixed: Signal<TData>[];
+};
+export type ApplyCommentsResult = 
+/** Every comment predates the PR's head commit — nothing new to address. */
+{
+    status: "no-new-comments";
+}
+/** The agent ran but left the working tree untouched, so nothing was pushed. */
+ | {
+    status: "no-changes";
+    comments: PrComment[];
+} | {
+    status: "comments-applied";
+    branch: string;
+    comments: PrComment[];
+};