@cueloop/schema 0.1.0-alpha.17 → 0.1.0-alpha.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/schema",
-  "version": "0.1.0-alpha.17",
+  "version": "0.1.0-alpha.18",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {

package/src/herdr.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { detectHerdr, insideHerdr, returnPaneFor } from "./herdr";
+
+describe("detectHerdr", () => {
+  test("null outside herdr, context inside", () => {
+    expect(detectHerdr({})).toBeNull();
+    expect(detectHerdr({ HERDR_ENV: "1", HERDR_PANE_ID: "p1" })).toBeNull();
+    expect(detectHerdr({ HERDR_ENV: "1", HERDR_PANE_ID: "p1", HERDR_BIN_PATH: "/x/herdr" })).toEqual({
+      paneId: "p1",
+      binPath: "/x/herdr",
+    });
+  });
+});
+
+describe("insideHerdr", () => {
+  test("true only when HERDR_ENV is exactly 1", () => {
+    expect(insideHerdr({})).toBeFalse();
+    expect(insideHerdr({ HERDR_ENV: "0" })).toBeFalse();
+    expect(insideHerdr({ HERDR_ENV: "1" })).toBeTrue();
+  });
+});
+
+describe("returnPaneFor", () => {
+  test("outside herdr there is never a return target", () => {
+    expect(returnPaneFor("w1:p1", {})).toBeUndefined();
+  });
+
+  test("env override wins, session meta is the fallback", () => {
+    const inside = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p9" };
+    expect(returnPaneFor("w1:p1", inside)).toBe("w1:p1");
+    expect(returnPaneFor("w1:p1", { ...inside, CUELOOP_RETURN_PANE: "w1:p2" })).toBe("w1:p2");
+  });
+
+  test("returning to our own pane is a no-op", () => {
+    expect(returnPaneFor("w1:p1", { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p1" })).toBeUndefined();
+  });
+});

package/src/herdr.ts

@@ -0,0 +1,43 @@
+/**
+ * The herdr ambient env contract, single-sourced. A process running inside a
+ * herdr pane sees HERDR_ENV=1 plus the pane id and the herdr binary path.
+ * Both the agent-side reporter (adapters) and the reviewer-side return-focus
+ * (client) read this contract; decoding it in one place stops the two sides
+ * drifting on which vars are required. Pure: no IO, env is only the default
+ * argument so callers can pass a fixture.
+ */
+
+export interface HerdrContext {
+  paneId: string;
+  binPath: string;
+}
+
+export type HerdrEnv = Record<string, string | undefined>;
+
+/**
+ * The pane's full contract - pane id and binary path - or null outside a
+ * functioning herdr. Required by anything that spawns the herdr CLI.
+ */
+export function detectHerdr(env: HerdrEnv = process.env): HerdrContext | null {
+  if (env.HERDR_ENV !== "1") return null;
+  const paneId = env.HERDR_PANE_ID;
+  const binPath = env.HERDR_BIN_PATH;
+  if (!paneId || !binPath) return null;
+  return { paneId, binPath };
+}
+
+/** True whenever this process runs inside a herdr pane. */
+export function insideHerdr(env: HerdrEnv = process.env): boolean {
+  return env.HERDR_ENV === "1";
+}
+
+/**
+ * The pane a closing review should hand focus back to: the opener's
+ * CUELOOP_RETURN_PANE, or the session's recorded pane, but never this pane
+ * itself. Undefined outside herdr or when the only candidate is our own pane.
+ */
+export function returnPaneFor(sessionHerdrPane?: string, env: HerdrEnv = process.env): string | undefined {
+  if (!insideHerdr(env)) return undefined;
+  const pane = env.CUELOOP_RETURN_PANE ?? sessionHerdrPane;
+  return pane && pane !== env.HERDR_PANE_ID ? pane : undefined;
+}

package/src/index.ts

@@ -4,3 +4,4 @@ export * from "./working-copy";
 export * from "./diff";
 export * from "./anchor";
 export * from "./feedback";
+export * from "./herdr";