@schlenkr/ragents 0.1.5 → 0.1.7

package/packages/workspace-executor/src/browser/contract.ts

@@ -0,0 +1,71 @@
+export const BROWSER_OPERATIONS = {
+  open: "browser.open",
+  snapshot: "browser.snapshot",
+  viewport: "browser.viewport",
+  click: "browser.click",
+  fill: "browser.fill",
+  select: "browser.select",
+  press: "browser.press",
+  check: "browser.check",
+  screenshot: "browser.screenshot",
+  state: "browser.state",
+  close: "browser.close",
+} as const;
+
+/** Nennt einen eigenen Chrome; auf einem Server setzt ihn die Profilsektion `ragents.browser`, auf einem Arbeitsplatz seine Umgebung. */
+export const BROWSER_EXECUTABLE_VARIABLE = "BROWSER_EXECUTABLE_PATH";
+
+export interface BrowserTarget {
+  role?: string;
+  name?: string;
+  label?: string;
+  text?: string;
+  testId?: string;
+  css?: string;
+  frame?: string;
+  nth?: number;
+  first?: boolean;
+}
+
+export interface BrowserViewport {
+  width: number;
+  height: number;
+}
+
+export interface BrowserSnapshot {
+  url: string;
+  title: string;
+  snapshot: string;
+  truncated: boolean;
+  errors: string[];
+}
+
+export interface BrowserCheck {
+  target?: BrowserTarget;
+  text?: string;
+  url?: string;
+  count?: number;
+  noErrors?: boolean;
+}
+
+/** Was eine bestandene Prüfung belegt; die Zeit setzt, wer die Evidenz des Runs hält. */
+export interface BrowserCheckResult {
+  url: string;
+  assertions: string[];
+}
+
+/** Der Stand der Seite nach einer Operation; der Aufrufer hält daraus die Evidenz des Runs. */
+export interface BrowserPageState {
+  url: string;
+  /** Seit der letzten Aktion oder Navigation hat eine Prüfung bestanden. */
+  checked: boolean;
+  errors: string[];
+  /** Die Kennungen der Aufnahmen seit der letzten Aktion oder Navigation, so wie der Aufrufer sie vergeben hat. */
+  screenshots: string[];
+}
+
+/** Das Ergebnis einer Operation an der Seite und der Stand, in dem sie die Seite hinterlässt. */
+export interface BrowserStep<T> {
+  result: T;
+  page: BrowserPageState;
+}

package/packages/workspace-executor/src/browser/module.ts

@@ -0,0 +1,74 @@
+import type { Browser } from "playwright-core";
+import { WorkspaceOperationError } from "../errors.js";
+import type { WorkspaceModuleFactory } from "../module.js";
+import { BROWSER_OPERATIONS, type BrowserCheck, type BrowserTarget, type BrowserViewport } from "./contract.js";
+import { BrowserPages } from "./pages.js";
+import { launchChromium } from "./playwright.js";
+
+const BROWSER_TIMEOUT_MS = 15_000;
+
+export interface BrowserModuleOptions {
+  /** Startet den Browser eines Runs; ohne Angabe Chrome über playwright-core aus dem Host dieser Maschine. */
+  launch?: (runId: string) => Promise<Browser>;
+  timeoutMs?: number;
+  checkTimeoutMs?: number;
+}
+
+const invalid = (message: string): WorkspaceOperationError => new WorkspaceOperationError("browser-input-invalid", message, 400);
+
+const fieldsOf = (input: unknown): Readonly<Record<string, unknown>> => {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) throw invalid("Die Eingabe einer Browseroperation ist ein Objekt");
+  return input as Readonly<Record<string, unknown>>;
+};
+
+const textOf = (input: unknown, key: string): string => {
+  const value = fieldsOf(input)[key];
+  if (typeof value !== "string") throw invalid(`Die Browseroperation braucht ${key} als Text`);
+  return value;
+};
+
+const targetOf = (input: unknown): BrowserTarget => {
+  const value = fieldsOf(input).target;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw invalid("Die Browseroperation braucht ein Ziel");
+  return value as BrowserTarget;
+};
+
+const viewportOf = (input: unknown): BrowserViewport => {
+  const { width, height } = fieldsOf(input);
+  if (typeof width !== "number" || typeof height !== "number" || !Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) {
+    throw invalid("Ein Viewport braucht Breite und Höhe als positive ganze Zahlen");
+  }
+  return { width, height };
+};
+
+/** Der Browser eines Runs auf dieser Maschine: Seite, Aktionen, Prüfungen und Aufnahmen; Evidenz und Ablage hält der Aufrufer. */
+export const browserModule = (options: BrowserModuleOptions = {}): WorkspaceModuleFactory => (host) => {
+  const timeoutMs = options.timeoutMs ?? BROWSER_TIMEOUT_MS;
+  const pages = new BrowserPages({
+    launch: options.launch ?? (async (runId) => launchChromium((await host.contextFor(runId)).hostRoot, runId, timeoutMs)),
+    timeoutMs,
+    checkTimeoutMs: options.checkTimeoutMs ?? Math.min(5_000, timeoutMs),
+  });
+  return {
+    operations: {
+      [BROWSER_OPERATIONS.open]: ({ runId, input, signal }) =>
+        pages.open(runId, textOf(input, "url"), viewportOf(fieldsOf(input).viewport), signal),
+      [BROWSER_OPERATIONS.snapshot]: ({ runId, signal }) => pages.snapshot(runId, signal),
+      [BROWSER_OPERATIONS.viewport]: ({ runId, input, signal }) => pages.viewport(runId, viewportOf(input), signal),
+      [BROWSER_OPERATIONS.click]: ({ runId, input, signal }) => pages.click(runId, targetOf(input), signal),
+      [BROWSER_OPERATIONS.fill]: ({ runId, input, signal }) => pages.fill(runId, targetOf(input), textOf(input, "value"), signal),
+      [BROWSER_OPERATIONS.select]: ({ runId, input, signal }) => pages.select(runId, targetOf(input), textOf(input, "label"), signal),
+      [BROWSER_OPERATIONS.press]: ({ runId, input, signal }) => pages.press(runId, targetOf(input), textOf(input, "key"), signal),
+      [BROWSER_OPERATIONS.check]: ({ runId, input, signal }) => pages.check(runId, fieldsOf(input) as BrowserCheck, signal),
+      [BROWSER_OPERATIONS.screenshot]: ({ runId, input, signal }) =>
+        pages.screenshot(runId, textOf(input, "id"), fieldsOf(input).fullPage === true, signal),
+      [BROWSER_OPERATIONS.state]: async ({ runId }) => pages.state(runId),
+      [BROWSER_OPERATIONS.close]: async ({ runId }) => {
+        await pages.close(runId);
+        return null;
+      },
+    },
+    stopRun: (runId) => pages.close(runId),
+    shutdown: () => pages.shutdown(),
+  };
+};

package/packages/workspace-executor/src/browser/pages.ts

@@ -0,0 +1,298 @@
+import type { Browser, Locator, Page } from "playwright-core";
+import type {
+  BrowserCheck,
+  BrowserCheckResult,
+  BrowserPageState,
+  BrowserSnapshot,
+  BrowserStep,
+  BrowserTarget,
+  BrowserViewport,
+} from "./contract.js";
+
+interface BrowserSession {
+  readonly browser: Promise<Browser>;
+  readonly viewport: BrowserViewport;
+  page?: Page;
+  queue: Promise<void>;
+  closed: boolean;
+  checked: boolean;
+  errors: string[];
+  /** Adressen, deren fehlgeschlagene Anfrage schon gemeldet ist; HTTP-Status, Konsole und Netzwerk melden dieselbe Ursache nur einmal. */
+  failedRequests: Set<string>;
+  screenshots: string[];
+}
+
+export interface BrowserPagesOptions {
+  launch: (runId: string) => Promise<Browser>;
+  timeoutMs: number;
+  checkTimeoutMs: number;
+}
+
+const errorText = (error: unknown): string => error instanceof Error ? error.message : String(error);
+const endedError = (): Error => new Error("Der Browserdienst dieses Executors ist beendet.");
+const maxSnapshotLength = 40_000;
+const ambiguityHint = "Wähle mit nth (0-basiert) oder first: true im Ziel einen Treffer, oder prüfe die Anzahl mit count in browser_check.";
+
+const withAmbiguityHint = (error: unknown): never => {
+  if (error instanceof Error && error.message.includes("strict mode violation")) throw new Error(`${error.message}\n${ambiguityHint}`, { cause: error });
+  throw error;
+};
+
+export const browserLocator = (page: Page, target: BrowserTarget): Locator => {
+  const selectors = [target.role, target.label, target.text, target.testId, target.css].filter((value) => value !== undefined);
+  if (selectors.length !== 1 || (target.name !== undefined && target.role === undefined)) {
+    throw new Error("Ein Browserziel braucht genau role (optional name), label, text, testId oder css.");
+  }
+  if (target.nth !== undefined && target.first) throw new Error("Ein Browserziel verwendet entweder nth oder first, nicht beides.");
+  const root = target.frame ? page.frameLocator(target.frame) : page;
+  const base = target.role ? root.getByRole(target.role as Parameters<Page["getByRole"]>[0], { name: target.name, exact: true })
+    : target.label ? root.getByLabel(target.label, { exact: true })
+      : target.text ? root.getByText(target.text, { exact: true })
+        : target.testId ? root.getByTestId(target.testId)
+          : root.locator(target.css!);
+  return target.first ? base.first() : target.nth !== undefined ? base.nth(target.nth) : base;
+};
+
+/** Je Run ein Browser mit einer Seite auf dieser Maschine; die Aktionen eines Runs laufen der Reihe nach. */
+export class BrowserPages {
+  readonly #options: BrowserPagesOptions;
+  readonly #sessions = new Map<string, BrowserSession>();
+  #shutDown = false;
+
+  constructor(options: BrowserPagesOptions) {
+    this.#options = options;
+  }
+
+  async open(runId: string, url: string, viewport: BrowserViewport, signal?: AbortSignal): Promise<BrowserStep<BrowserSnapshot>> {
+    if (this.#shutDown) throw endedError();
+    const parsed = new URL(url);
+    if (!["http:", "https:"].includes(parsed.protocol)) throw new Error("browser_open braucht eine HTTP- oder HTTPS-Adresse.");
+    signal?.throwIfAborted();
+    if (!this.#sessions.has(runId)) this.#start(runId, viewport);
+    return this.#perform(runId, signal, async (session, page) => {
+      this.#resetEvidence(session);
+      const response = await page.goto(parsed.href, { waitUntil: "domcontentloaded" });
+      if (response && !response.ok()) throw new Error(`Browsernavigation fehlgeschlagen: HTTP ${response.status()} (${page.url()}).`);
+      return this.#snapshot(session, page);
+    });
+  }
+
+  snapshot(runId: string, signal?: AbortSignal): Promise<BrowserStep<BrowserSnapshot>> {
+    return this.#perform(runId, signal, (session, page) => this.#snapshot(session, page));
+  }
+
+  viewport(runId: string, viewport: BrowserViewport, signal?: AbortSignal): Promise<BrowserStep<BrowserSnapshot>> {
+    return this.#perform(runId, signal, async (session, page) => {
+      await page.setViewportSize(viewport);
+      return this.#snapshot(session, page);
+    });
+  }
+
+  click(runId: string, target: BrowserTarget, signal?: AbortSignal): Promise<BrowserStep<BrowserSnapshot>> {
+    return this.#action(runId, target, signal, (locator) => locator.click());
+  }
+
+  fill(runId: string, target: BrowserTarget, value: string, signal?: AbortSignal): Promise<BrowserStep<BrowserSnapshot>> {
+    return this.#action(runId, target, signal, (locator) => locator.fill(value));
+  }
+
+  select(runId: string, target: BrowserTarget, label: string, signal?: AbortSignal): Promise<BrowserStep<BrowserSnapshot>> {
+    return this.#action(runId, target, signal, (locator) => locator.selectOption({ label }));
+  }
+
+  press(runId: string, target: BrowserTarget, key: string, signal?: AbortSignal): Promise<BrowserStep<BrowserSnapshot>> {
+    return this.#action(runId, target, signal, (locator) => locator.press(key));
+  }
+
+  check(runId: string, input: BrowserCheck, signal?: AbortSignal): Promise<BrowserStep<BrowserCheckResult>> {
+    return this.#perform(runId, signal, async (session, page) => {
+      session.checked = false;
+      if (!input.target && input.text === undefined && input.url === undefined && input.noErrors !== true) {
+        throw new Error("browser_check braucht mindestens target, text, url oder noErrors: true.");
+      }
+      if (input.count !== undefined && (!input.target || input.target.nth !== undefined || input.target.first)) {
+        throw new Error("count in browser_check braucht ein target ohne nth oder first und zählt dessen sichtbare Treffer.");
+      }
+      const timeout = this.#options.checkTimeoutMs;
+      const assertions: string[] = [];
+      if (input.target && input.count !== undefined) {
+        const visible = browserLocator(page, input.target).filter({ visible: true });
+        const found = await this.#waitForCount(visible, input.count, timeout);
+        if (found !== input.count) throw new Error(`Erwartet ${input.count} sichtbare Treffer, gefunden ${found}.`);
+        assertions.push(`${input.count} sichtbare Treffer`);
+      } else if (input.target) {
+        const locator = browserLocator(page, input.target);
+        await locator.waitFor({ state: "visible", timeout }).catch(withAmbiguityHint);
+        assertions.push("Ziel ist sichtbar");
+        if (input.text !== undefined) {
+          try { await locator.filter({ hasText: input.text }).waitFor({ state: "visible", timeout }); }
+          catch (error) { throw new Error(`Erwarteter Text fehlt im Ziel: ${input.text}`, { cause: error }); }
+          assertions.push(`Text im Ziel: ${input.text}`);
+        }
+      } else if (input.text !== undefined) {
+        await page.getByText(input.text, { exact: false }).first().waitFor({ state: "visible", timeout });
+        assertions.push(`Sichtbarer Text: ${input.text}`);
+      }
+      if (input.url !== undefined) {
+        await page.waitForURL(input.url, { timeout });
+        assertions.push(`Adresse: ${input.url}`);
+      }
+      if (input.noErrors !== false) {
+        if (session.errors.length > 0) throw new Error(`Browserfehler: ${session.errors.join("\n")}`);
+        assertions.push("Keine erfassten Browser- oder Netzwerkfehler seit der Navigation");
+      }
+      session.checked = true;
+      return { url: page.url(), assertions };
+    });
+  }
+
+  /** Nimmt die Seite als PNG auf und liefert es Base64-kodiert; `id` merkt sich die Seite als aktuelle Aufnahme. */
+  screenshot(runId: string, id: string, fullPage: boolean, signal?: AbortSignal): Promise<BrowserStep<string>> {
+    return this.#perform(runId, signal, async (session, page) => {
+      const image = await page.screenshot({ fullPage, type: "png", timeout: this.#options.timeoutMs });
+      session.screenshots.push(id);
+      return image.toString("base64");
+    });
+  }
+
+  /** Der Stand der Seite, ohne auf laufende Aktionen zu warten; ohne offene Seite `null`. */
+  state(runId: string): BrowserPageState | null {
+    const session = this.#sessions.get(runId);
+    return session && !session.closed && session.page ? this.#stateOf(session, session.page) : null;
+  }
+
+  async close(runId: string): Promise<void> {
+    const session = this.#sessions.get(runId);
+    if (!session) return;
+    session.closed = true;
+    this.#sessions.delete(runId);
+    const browser = await session.browser.catch(() => undefined);
+    if (browser) await browser.close();
+    await session.queue;
+  }
+
+  /** Schließt jeden Browser; danach startet keiner mehr, weil niemand ihn schließen würde. */
+  async shutdown(): Promise<void> {
+    this.#shutDown = true;
+    const results = await Promise.allSettled([...this.#sessions.keys()].map((runId) => this.close(runId)));
+    const failed = results.find((result): result is PromiseRejectedResult => result.status === "rejected");
+    if (failed) throw failed.reason;
+  }
+
+  #start(runId: string, viewport: BrowserViewport): void {
+    const session: BrowserSession = {
+      browser: this.#launch(runId),
+      viewport,
+      queue: Promise.resolve(),
+      closed: false,
+      checked: false,
+      errors: [],
+      failedRequests: new Set(),
+      screenshots: [],
+    };
+    this.#sessions.set(runId, session);
+    void session.browser.catch(() => {
+      session.closed = true;
+      if (this.#sessions.get(runId) === session) this.#sessions.delete(runId);
+    });
+  }
+
+  async #launch(runId: string): Promise<Browser> {
+    return this.#options.launch(runId);
+  }
+
+  async #waitForCount(locator: Locator, expected: number, timeout: number): Promise<number> {
+    const deadline = Date.now() + timeout;
+    let found = await locator.count();
+    while (found !== expected && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      found = await locator.count();
+    }
+    return found;
+  }
+
+  #resetEvidence(session: BrowserSession): void {
+    session.checked = false;
+    session.screenshots = [];
+    session.errors = [];
+    session.failedRequests = new Set();
+  }
+
+  async #page(session: BrowserSession): Promise<Page> {
+    if (session.closed) throw new Error("Der Browser wurde beendet.");
+    if (session.page) return session.page;
+    const browser = await session.browser;
+    if (session.closed) throw new Error("Der Browser wurde beendet.");
+    const context = await browser.newContext({ viewport: session.viewport });
+    context.setDefaultTimeout(this.#options.timeoutMs);
+    context.setDefaultNavigationTimeout(this.#options.timeoutMs);
+    const page = await context.newPage();
+    const addError = (text: string) => {
+      session.errors.push(text.slice(0, 2000));
+      if (session.errors.length > 100) session.errors.shift();
+    };
+    const addRequestError = (url: string, text: string) => {
+      if (session.failedRequests.has(url)) return;
+      session.failedRequests.add(url);
+      addError(text);
+    };
+    page.on("console", (message) => {
+      if (message.type() !== "error") return;
+      const source = message.text().startsWith("Failed to load resource") ? message.location().url : "";
+      if (source) addRequestError(source, `Konsole: ${message.text()} (${source})`);
+      else addError(`Konsole: ${message.text()}`);
+    });
+    page.on("pageerror", (error) => addError(`JavaScript: ${error.message}`));
+    page.on("requestfailed", (request) => addRequestError(request.url(), `Netzwerk: ${request.method()} ${request.url()} ${request.failure()?.errorText}`));
+    page.on("response", (response) => { if (response.status() >= 400) addRequestError(response.url(), `HTTP ${response.status()}: ${response.url()}`); });
+    page.on("framenavigated", (frame) => { if (frame === page.mainFrame()) this.#resetEvidence(session); });
+    page.on("popup", (popup) => {
+      addError(`Die Anwendung hat ein neues Fenster geöffnet: ${popup.url()}. Popups werden nicht bedient.`);
+      void popup.close().catch((error) => addError(`Fenster schließen: ${errorText(error)}`));
+    });
+    session.page = page;
+    return page;
+  }
+
+  #perform<T>(runId: string, signal: AbortSignal | undefined, action: (session: BrowserSession, page: Page) => Promise<T>): Promise<BrowserStep<T>> {
+    if (this.#shutDown) return Promise.reject(endedError());
+    const session = this.#sessions.get(runId);
+    if (!session || session.closed) return Promise.reject(new Error("Für diesen Run ist kein Browser offen. Zuerst browser_open aufrufen."));
+    const pending = session.queue.then(async () => {
+      signal?.throwIfAborted();
+      const abort = () => { void this.close(runId).catch((error) => console.error("Browserstopp fehlgeschlagen:", errorText(error))); };
+      signal?.addEventListener("abort", abort, { once: true });
+      try {
+        const page = await this.#page(session);
+        signal?.throwIfAborted();
+        const result = await action(session, page);
+        signal?.throwIfAborted();
+        if (session.closed) throw new Error("Der Browser wurde beendet.");
+        return { result, page: this.#stateOf(session, page) };
+      } finally {
+        signal?.removeEventListener("abort", abort);
+      }
+    });
+    session.queue = pending.then(() => undefined, () => undefined);
+    return pending;
+  }
+
+  #action(runId: string, target: BrowserTarget, signal: AbortSignal | undefined, action: (locator: Locator) => Promise<unknown>): Promise<BrowserStep<BrowserSnapshot>> {
+    return this.#perform(runId, signal, async (session, page) => {
+      session.checked = false;
+      session.screenshots = [];
+      await action(browserLocator(page, target)).catch(withAmbiguityHint);
+      return this.#snapshot(session, page);
+    });
+  }
+
+  #stateOf(session: BrowserSession, page: Page): BrowserPageState {
+    return { url: page.url(), checked: session.checked, errors: [...session.errors], screenshots: [...session.screenshots] };
+  }
+
+  async #snapshot(session: BrowserSession, page: Page): Promise<BrowserSnapshot> {
+    const snapshot = await page.locator("body").ariaSnapshot({ mode: "ai", timeout: this.#options.timeoutMs });
+    return { url: page.url(), title: await page.title(), snapshot: snapshot.slice(0, maxSnapshotLength),
+      truncated: snapshot.length > maxSnapshotLength, errors: [...session.errors] };
+  }
+}

package/packages/workspace-executor/src/browser/playwright.ts

@@ -0,0 +1,52 @@
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import path from "node:path";
+import type { Browser } from "playwright-core";
+import { RUN_MARKER_ENV } from "../run-marker.js";
+import { safeProcessEnvironment } from "../safe-environment.js";
+import { BROWSER_EXECUTABLE_VARIABLE } from "./contract.js";
+
+type Playwright = typeof import("playwright-core");
+
+const messageOf = (cause: unknown): string => cause instanceof Error ? cause.message : String(cause);
+
+/** playwright-core liegt in den node_modules des Hosts dieser Maschine und wird erst im Aufruf geladen, nie mit dem Executor. */
+export const hostPlaywright = (hostRoot: string | undefined): Playwright => {
+  if (!hostRoot) {
+    throw new Error("Für die Browserprüfung ist auf diesem Rechner kein Host bekannt, aus dem sich playwright-core auflösen "
+      + "ließe. Ein Arbeitsplatz bekommt ihn mit der ersten Verbindung zu einem verteilenden Server oder über die "
+      + "Einstellung ragents.hostPath");
+  }
+  const load = createRequire(path.join(hostRoot, "package.json"));
+  try {
+    return load("playwright-core") as Playwright;
+  } catch (cause) {
+    throw new Error(`playwright-core liegt nicht im Host ${hostRoot}: ${messageOf(cause)}`);
+  }
+};
+
+/** Der Chrome dieser Maschine: der aus ihrer Umgebung, sonst das Chromium, das die Provisionierung für playwright-core holt. */
+export const browserExecutable = async (playwright: Playwright, environment: NodeJS.ProcessEnv = process.env): Promise<string> => {
+  const configured = environment[BROWSER_EXECUTABLE_VARIABLE];
+  const candidate = configured ? configured : playwright.chromium.executablePath();
+  if (await access(candidate, constants.X_OK).then(() => true, () => false)) return candidate;
+  throw new Error((configured
+    ? `${BROWSER_EXECUTABLE_VARIABLE} nennt ${configured}; dort gibt es auf diesem Rechner keinen ausführbaren Browser. `
+    : `Auf diesem Rechner gibt es keinen ausführbaren Browser: ${BROWSER_EXECUTABLE_VARIABLE} ist nicht gesetzt und Chromium fehlt unter ${candidate}. `)
+    + "Ein Arbeitsplatz holt Chromium mit pnpm provision --workspace, ein Server mit pnpm provision <profil>; "
+    + `${BROWSER_EXECUTABLE_VARIABLE} nennt einen vorhandenen Chrome, auf einem Server in der Profilsektion ragents.browser, `
+    + "auf einem Arbeitsplatz in seiner Umgebung.");
+};
+
+/** Startet Chrome headless mit der Umgebung dieser Maschine und dem Marker des Runs, damit die Prozessanzeige ihn zuordnet. */
+export const launchChromium = async (hostRoot: string | undefined, runId: string, timeoutMs: number): Promise<Browser> => {
+  const playwright = hostPlaywright(hostRoot);
+  return playwright.chromium.launch({
+    executablePath: await browserExecutable(playwright),
+    headless: true,
+    timeout: timeoutMs,
+    env: { ...safeProcessEnvironment(process.env), HOME: homedir(), [RUN_MARKER_ENV]: runId },
+  });
+};

package/packages/workspace-executor/src/commands.ts

@@ -0,0 +1,170 @@
+import type { WorkspaceProcessContext } from "./context.js";
+import { WorkspaceOperationError } from "./errors.js";
+import { workspaceDirectory } from "./files.js";
+import { runManagedProcess } from "./managed-process.js";
+import type { WorkspaceModuleFactory, WorkspaceOperation } from "./module.js";
+import type { OperationFootprint } from "./paths.js";
+import { sandboxedLaunch } from "./process-sandbox.js";
+
+export const COMMAND_OPERATIONS = {
+  run: "commands.run",
+} as const;
+
+/** Die größte Ausgabe je Datenstrom, die ein Aufruf zurückgibt; was darüber hinausgeht, verwirft er und meldet die Kürzung. */
+export const COMMAND_OUTPUT_LIMIT = 2 * 1024 * 1024;
+
+export interface CommandRunInput {
+  /** Ein Name aus dem PATH des Executors oder der Pfad eines Programms; es läuft ohne Shell. */
+  program: string;
+  args?: readonly string[];
+  /** Der Arbeitsordner relativ zur Wurzel des Runs; ohne Angabe die Wurzel selbst. */
+  cwd?: string;
+  timeoutMs: number;
+  /** Höchstens so viele Bytes je Datenstrom; ohne Angabe `COMMAND_OUTPUT_LIMIT`. */
+  maxOutputBytes?: number;
+}
+
+export interface CommandResult {
+  /** `null`, wenn der Prozess durch ein Signal endete. */
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+  stdoutTruncated: boolean;
+  stderrTruncated: boolean;
+}
+
+interface CheckedCommand {
+  readonly program: string;
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly timeoutMs: number;
+  readonly maxOutputBytes: number;
+}
+
+interface RunningCommand {
+  readonly controller: AbortController;
+  readonly finished: Promise<unknown>;
+}
+
+const invalid = (message: string): WorkspaceOperationError => new WorkspaceOperationError("command-invalid", message, 400);
+
+const textWithoutNul = (value: unknown): value is string => typeof value === "string" && !value.includes("\0");
+
+const checkedCommand = (input: unknown, platform: NodeJS.Platform): CheckedCommand => {
+  const value = (input ?? {}) as Partial<Record<keyof CommandRunInput, unknown>>;
+  const { program, args = [], cwd = "", timeoutMs, maxOutputBytes = COMMAND_OUTPUT_LIMIT } = value;
+  if (!textWithoutNul(program) || program === "") throw invalid("Der Befehl braucht ein Programm als Text");
+  if (platform === "win32" && /\.(cmd|bat)$/i.test(program)) throw invalid(`${program} braucht unter Windows eine Shell; ein Befehl läuft ohne`);
+  if (!Array.isArray(args) || !args.every(textWithoutNul)) throw invalid("Die Argumente müssen Texte ohne Nullzeichen sein");
+  if (typeof cwd !== "string") throw invalid("Der Arbeitsordner muss ein Text sein");
+  if (typeof timeoutMs !== "number" || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
+    throw invalid("Die Zeitgrenze muss eine positive ganze Zahl in Millisekunden sein");
+  }
+  if (typeof maxOutputBytes !== "number" || !Number.isSafeInteger(maxOutputBytes) || maxOutputBytes < 0 || maxOutputBytes > COMMAND_OUTPUT_LIMIT) {
+    throw invalid(`Die Ausgabegrenze liegt zwischen 0 und ${COMMAND_OUTPUT_LIMIT} Bytes`);
+  }
+  return { program, args, cwd, timeoutMs, maxOutputBytes };
+};
+
+/** Sammelt einen Datenstrom bis zur Grenze; der Rest wird verworfen, der Prozess läuft weiter. */
+const boundedOutput = (limit: number) => {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  let truncated = false;
+  return {
+    add: (chunk: Buffer): void => {
+      const kept = chunk.subarray(0, Math.max(0, limit - size));
+      if (kept.length < chunk.length) truncated = true;
+      if (kept.length === 0) return;
+      chunks.push(kept);
+      size += kept.length;
+    },
+    text: (): string => Buffer.concat(chunks, size).toString("utf8"),
+    truncated: (): boolean => truncated,
+  };
+};
+
+const unavailable = (program: string, error: unknown): WorkspaceOperationError | undefined => {
+  const code = (error as NodeJS.ErrnoException).code;
+  if (code === "ENOENT") return new WorkspaceOperationError("command-unavailable", `Das Programm ${program} gibt es auf diesem Rechner nicht`, 409);
+  if (code === "EACCES") return new WorkspaceOperationError("command-unavailable", `Das Programm ${program} ist auf diesem Rechner nicht ausführbar`, 409);
+  return undefined;
+};
+
+const runCommand = async (context: WorkspaceProcessContext, command: CheckedCommand, signal: AbortSignal): Promise<CommandResult> => {
+  const cwd = await workspaceDirectory(context.root, command.cwd);
+  const stdout = boundedOutput(command.maxOutputBytes);
+  const stderr = boundedOutput(command.maxOutputBytes);
+  const launch = await sandboxedLaunch(context, { command: command.program, args: command.args });
+  signal.throwIfAborted();
+  const result = await runManagedProcess({
+    command: launch.command,
+    args: [...launch.args],
+    cwd,
+    env: context.env,
+    uid: context.uid,
+    gid: context.gid,
+    label: command.program,
+    signal,
+    timeoutMs: command.timeoutMs,
+    onStdout: stdout.add,
+    onStderr: stderr.add,
+  }).catch((error: unknown) => {
+    throw unavailable(command.program, error) ?? error;
+  });
+  if (result.timedOut) {
+    throw new WorkspaceOperationError("command-timeout", `${command.program} hat die Zeitgrenze von ${command.timeoutMs} ms überschritten`, 504);
+  }
+  return {
+    exitCode: result.code,
+    stdout: stdout.text(),
+    stderr: stderr.text(),
+    stdoutTruncated: stdout.truncated(),
+    stderrTruncated: stderr.truncated(),
+  };
+};
+
+/** Ein Befehl läuft in der Wurzel des Runs, ein Alias gilt dort nicht; seine Zeitgrenze verlängert, wie lange ein entfernter Executor auf ihn warten darf. */
+const commandFootprint = (input: unknown): OperationFootprint => {
+  const timeoutMs = typeof input === "object" && input !== null ? (input as { timeoutMs?: unknown }).timeoutMs : undefined;
+  return { roots: { aliases: [], runRoot: true }, ...(typeof timeoutMs === "number" && timeoutMs > 0 ? { durationMs: timeoutMs } : {}) };
+};
+
+/** Befehle im Arbeitsbereich des Runs: ein Programm mit Argumenten, ohne Shell, in einem Ordner unter der Wurzel, mit der Umgebung dieses Executors. */
+export const commandModule = (platform: NodeJS.Platform = process.platform): WorkspaceModuleFactory => (host) => {
+  const running = new Map<string, Set<RunningCommand>>();
+  const stopAll = async (commands: readonly RunningCommand[]): Promise<void> => {
+    for (const command of commands) command.controller.abort(new Error("Der Befehl wurde mit seinem Run beendet"));
+    await Promise.allSettled(commands.map((command) => command.finished));
+  };
+  const run: WorkspaceOperation = async ({ runId, input, signal }) => {
+    const command = checkedCommand(input, platform);
+    const controller = new AbortController();
+    const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+    const finished = (async (): Promise<CommandResult> => {
+      const context = await host.contextFor(runId);
+      combined.throwIfAborted();
+      const execute = (): Promise<CommandResult> => runCommand(context, command, combined);
+      return context.runOperation ? context.runOperation(execute) : execute();
+    })();
+    const entry: RunningCommand = { controller, finished };
+    const commands = running.get(runId) ?? new Set<RunningCommand>();
+    running.set(runId, commands.add(entry));
+    try {
+      return await finished;
+    } finally {
+      commands.delete(entry);
+      if (commands.size === 0) running.delete(runId);
+    }
+  };
+  return {
+    operations: {
+      [COMMAND_OPERATIONS.run]: run,
+    },
+    footprints: {
+      [COMMAND_OPERATIONS.run]: commandFootprint,
+    },
+    stopRun: (runId) => stopAll([...running.get(runId) ?? []]),
+    shutdown: () => stopAll([...running.values()].flatMap((commands) => [...commands])),
+  };
+};