@schlenkr/ragents 0.1.10 → 0.1.11

package/scripts/package/build-package.ts

@@ -11,7 +11,7 @@ import { assertBundleStand, readBundleManifest, sourceStandOf } from "../../apps
 import { builtInPluginFolders } from "../plugin/build-builtin-plugins.ts";
 
 export const PACKAGE_NAME = "@schlenkr/ragents";
-/** Der Ordner unter dist/; der Paketname hat einen Scope, der Ordnername bleibt schlicht. */
+/** The folder under dist/; the package name has a scope, the folder name stays plain. */
 export const PACKAGE_FOLDER = "ragents";
 
 const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
@@ -19,12 +19,12 @@ const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url))
 const SKIPPED_FOLDERS = new Set(["node_modules", "dist", ".git"]);
 const SKIPPED_FILES = new Set([".DS_Store"]);
 
-/** Die Prüfungen der Unterbefehle laufen im Checkout; im Paket wäre nur ihr Testmaterial zu sehen. */
+/** The subcommands' tests run in the checkout; in the package only their test material would be visible. */
 const SKIPPED_IN_PACKAGE = /^scripts\/.*\.test\.tsx?$/;
 
 const packagePath = (packageRoot: string, file: string): string => path.relative(packageRoot, file).split(path.sep).join("/");
 
-/** Die neutralen Profile des Repositories; ragents start fährt sie aus dem Paket wie aus dem Checkout. */
+/** The repository's neutral profiles; ragents start runs them from the package as from the checkout. */
 export const PACKAGED_PROFILES = ["core", "developer", "showcase"] as const;
 
 export const PACKAGE_LICENSE = "PolyForm-Shield-1.0.0";
@@ -32,7 +32,7 @@ export const PACKAGE_AUTHOR = "Ronald Schlenker";
 export const REPOSITORY_URL = "https://github.com/SchlenkR/RAgents";
 export const PACKAGE_KEYWORDS = ["agents", "llm", "actors", "typescript", "csharp", "fsharp", "vscode"] as const;
 
-/** Lizenz und Listing-README liegen an der Wurzel des Pakets, ihre Quellen im Repository woanders. */
+/** License and listing README are at the root of the package, their sources elsewhere in the repository. */
 export const PACKAGE_ROOT_FILES: readonly (readonly [string, string])[] = [
   ["LICENSE", "LICENSE"],
   ["scripts/package/README.md", "README.md"],
@@ -42,7 +42,7 @@ const ROOT_FILE_SOURCES = new Set(PACKAGE_ROOT_FILES.map(([source]) => source));
 
 const skippedInPackage = (relative: string): boolean => SKIPPED_IN_PACKAGE.test(relative) || ROOT_FILE_SOURCES.has(relative);
 
-/** Was der Host zur Laufzeit lädt: Server, Engine, das fertige Web, die eingebauten Bundles, Plugin-Quellen für Verträge und das Bauwerkzeug, Profile und die Skripte hinter den Unterbefehlen; dazu kommen die Typen aus declarationFolders. */
+/** What the host loads at runtime: server, engine, the built web, the built-in bundles, plugin sources for contracts and the build tool, profiles and the scripts behind the subcommands; plus the types from declarationFolders. */
 export const packageContents = (root = repositoryRoot): readonly string[] => [
   "apps/server/package.json",
   "apps/server/tsconfig.json",
@@ -67,7 +67,7 @@ export const packageContents = (root = repositoryRoot): readonly string[] => [
   "scripts/workspace-client",
 ];
 
-/** Die gegabelte Agentenlaufzeit läuft aus ihren Quellen, ihre Typen gibt es nur gebaut; das Bauwerkzeug prüft fremde Plugins gegen sie. */
+/** The forked agent runtime runs from its sources, its types exist only built; the build tool checks third-party plugins against them. */
 export const declarationFolders = (root = repositoryRoot): readonly string[] =>
   readdirSync(path.join(root, "packages"), { withFileTypes: true })
     .filter((entry) => entry.isDirectory())
@@ -78,13 +78,13 @@ export const declarationFolders = (root = repositoryRoot): readonly string[] =>
     })
     .map((entry) => `packages/${entry.name}/dist`);
 
-/** Was der Host ausführt, in eine Mini-App bündelt oder beim Bauen eines Plugins liest. */
+/** What the host executes, bundles into a mini-app or reads when building a plugin. */
 const SCANNED = ["apps/server/src", "apps/web", "packages", "plugins", "scripts"];
 const PACKAGE_NAME_PATTERN = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
 const SCAN_SKIPPED = new Set(["node_modules", "dist"]);
 const SCANNED_EXTENSIONS = new Set([".ts", ".tsx", ".mts", ".mjs", ".js", ".css"]);
 const IMPORT_PATTERN = /\b(?:from|import|require(?:\.resolve)?)\s*\(?\s*["']([^"'\n]+)["']/g;
-/** Ein Beitrag zum Executor löst Pakete zur Laufzeit aus dem Host auf; auch sie muss das Paket tragen. */
+/** An executor contribution resolves packages from the host at runtime; the package must carry them too. */
 const HOST_PACKAGE_PATTERN = /\bhostPackageFile\([^,()]*,\s*["']([^"'\n]+)["']/g;
 
 const files = async (folder: string, skippedFolders: ReadonlySet<string> = SKIPPED_FOLDERS): Promise<readonly string[]> => {
@@ -142,12 +142,12 @@ const declaredWebDependencies = (packageDirectory: string): readonly string[] =>
   return Object.keys(declared);
 };
 
-/** Die Pakete, die der ausgeführte Teil des Pakets wirklich importiert, plus die zur Laufzeit verlinkten Bibliotheken
- * und die, die das Web des Hosts den web-Hälften fremder Plugins anbietet. */
+/** The packages that the executed part of the package actually imports, plus the libraries linked at runtime
+ * and those that the host's web offers to the web halves of third-party plugins. */
 export const requiredPackages = (packageDirectory: string): ReadonlyMap<string, string> => {
   const sources = new Map<string, string>();
-  for (const name of runtimeLibraries) sources.set(name, "plugins/ragents.actor-programs (verlinkt zur Laufzeit)");
-  for (const name of declaredWebDependencies(packageDirectory)) sources.set(name, "apps/web/package.json (für die web-Hälften der Plugins)");
+  for (const name of runtimeLibraries) sources.set(name, "plugins/ragents.actor-programs (linked at runtime)");
+  for (const name of declaredWebDependencies(packageDirectory)) sources.set(name, "apps/web/package.json (for the web halves of the plugins)");
   for (const folder of scanRoots(packageDirectory)) {
     for (const file of scannedFiles(folder)) {
       const content = readFileSync(file, "utf8");
@@ -179,7 +179,7 @@ const anchors = (root: string): readonly string[] => [
     .filter((file) => statSync(file, { throwIfNoEntry: false })?.isFile() === true)),
 ];
 
-/** Die Fassungen, die dieser Checkout für ein Paket installiert hat; die jüngste kommt ins Paket. */
+/** The versions this checkout has installed for a package; the newest goes into the package. */
 export const installedVersions = (name: string, root = repositoryRoot): readonly string[] => {
   const found = new Set<string>();
   for (const anchor of anchors(root)) {
@@ -193,7 +193,7 @@ export const installedVersions = (name: string, root = repositoryRoot): readonly
     }
   }
   const versions = [...found].sort(compareVersions);
-  if (versions.length === 0) throw new Error(`Das Paket ${name} ist in diesem Checkout nicht installiert; ohne Fassung kann es nicht ins Paket`);
+  if (versions.length === 0) throw new Error(`The package ${name} is not installed in this checkout; without a version it cannot go into the package`);
   return versions;
 };
 
@@ -205,25 +205,25 @@ export interface BuiltPackage {
   readonly flattened: readonly string[];
 }
 
-/** Das Paket liefert das Web fertig aus; es muss gebaut sein und zu seinen Quellen passen. */
+/** The package ships the web prebuilt; it must be built and match its sources. */
 const assertHostWeb = (root: string): void => {
   const problem = hostWebProblem(hostWebDirectory(root), root, isCheckout(root));
-  if (problem) throw new Error(`${problem}; vorher pnpm build:web`);
+  if (problem) throw new Error(`${problem}; run pnpm build:web first`);
 };
 
-/** Jedes eingebaute Plugin muss als Bundle vorliegen und zu seinen Quellen passen, sonst startet das Paket kein Profil. */
+/** Every built-in plugin must exist as a bundle and match its sources, otherwise the package starts no profile. */
 const assertBuiltInBundles = (root: string): void => {
   for (const folder of builtInPluginFolders(path.join(root, "plugins"))) {
     const bundle = path.join(root, "bundles", path.basename(folder));
-    if (!statSync(bundle, { throwIfNoEntry: false })?.isDirectory()) throw new Error(`Das Bundle ${bundle} fehlt; vorher pnpm build:plugins`);
-    if (readBundleManifest(bundle).sourceStand !== sourceStandOf(folder)) throw new Error(`Das Bundle ${bundle} passt nicht mehr zu ${folder}; vorher pnpm build:plugins`);
+    if (!statSync(bundle, { throwIfNoEntry: false })?.isDirectory()) throw new Error(`The bundle ${bundle} is missing; run pnpm build:plugins first`);
+    if (readBundleManifest(bundle).sourceStand !== sourceStandOf(folder)) throw new Error(`The bundle ${bundle} no longer matches ${folder}; run pnpm build:plugins first`);
   }
 };
 
 const copyDeclarations = async (root: string, target: string): Promise<readonly string[]> => {
   const copied: string[] = [];
   for (const folder of declarationFolders(root)) {
-    if (!statSync(path.join(root, folder), { throwIfNoEntry: false })?.isDirectory()) throw new Error(`${folder} fehlt; vorher pnpm build:agent`);
+    if (!statSync(path.join(root, folder), { throwIfNoEntry: false })?.isDirectory()) throw new Error(`${folder} is missing; run pnpm build:agent first`);
     for (const file of (await files(path.join(root, folder))).filter((name) => name.endsWith(".d.ts"))) {
       const destination = path.join(target, path.relative(root, file));
       await mkdir(path.dirname(destination), { recursive: true });
@@ -242,7 +242,7 @@ export const buildPackage = async (target: string, root = repositoryRoot): Promi
   let fileCount = 0;
   let byteSize = 0;
   for (const entry of packageContents(root)) {
-    // Ein Bundle ist fertig gebaut und kommt ganz ins Paket, auch ein Asset-Ordner namens dist.
+    // A bundle is fully built and goes into the package completely, including an asset folder named dist.
     const copied = await copyTo(path.join(root, entry), path.join(target, entry), target, entry === "bundles" ? new Set() : undefined);
     fileCount += copied.length;
     for (const file of copied) byteSize += statSync(file).size;
@@ -272,7 +272,7 @@ export const buildPackage = async (target: string, root = repositoryRoot): Promi
   const manifest = {
     name: PACKAGE_NAME,
     version: readPackageVersion(root),
-    description: "RAgents-Host: Server, Engine, Plugins und Werkzeuge ohne Quell-Checkout",
+    description: "RAgents host: server, engine, plugins and tools without a source checkout",
     keywords: [...PACKAGE_KEYWORDS],
     homepage: "https://schlenkr.github.io/RAgents/",
     bugs: { url: `${REPOSITORY_URL}/issues` },
@@ -296,18 +296,18 @@ export const buildPackage = async (target: string, root = repositoryRoot): Promi
 const main = async (): Promise<void> => {
   const pack = process.argv.includes("--pack");
   const unknown = process.argv.slice(2).filter((argument) => argument !== "--pack");
-  if (unknown.length) throw new Error(`Unbekanntes Argument: ${unknown.join(" ")} (erlaubt: --pack)`);
+  if (unknown.length) throw new Error(`Unknown argument: ${unknown.join(" ")} (allowed: --pack)`);
   const target = path.join(repositoryRoot, "dist", PACKAGE_FOLDER);
   const built = await buildPackage(target);
-  console.log(`== Paket ${PACKAGE_NAME}@${built.manifest.version as string} in ${built.directory}`);
-  console.log(`== Host-Version ${(built.manifest.ragents as { hostVersion: string }).hostVersion}`);
-  console.log(`== ${built.fileCount} Dateien, ${(built.byteSize / 1024 / 1024).toFixed(1)} MB, ${Object.keys(built.manifest.dependencies as object).length} Abhängigkeiten`);
+  console.log(`== Package ${PACKAGE_NAME}@${built.manifest.version as string} in ${built.directory}`);
+  console.log(`== Host version ${(built.manifest.ragents as { hostVersion: string }).hostVersion}`);
+  console.log(`== ${built.fileCount} files, ${(built.byteSize / 1024 / 1024).toFixed(1)} MB, ${Object.keys(built.manifest.dependencies as object).length} dependencies`);
   for (const [name, version] of Object.entries(built.manifest.dependencies as Record<string, string>)) console.log(`   ${name}@${version}`);
-  for (const entry of built.flattened) console.log(`== Mehrfachfassung abgeflacht: ${entry}`);
+  for (const entry of built.flattened) console.log(`== Multiple versions flattened: ${entry}`);
   if (!pack) return;
   const packed = spawnSync("npm", ["pack", "--pack-destination", path.dirname(built.directory)], { cwd: built.directory, encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] });
-  if (packed.status !== 0) throw new Error(`npm pack endete mit Code ${packed.status}`);
-  console.log(`== Archiv ${path.join(path.dirname(built.directory), packed.stdout.trim().split("\n").at(-1) ?? "")}`);
+  if (packed.status !== 0) throw new Error(`npm pack ended with code ${packed.status}`);
+  console.log(`== Archive ${path.join(path.dirname(built.directory), packed.stdout.trim().split("\n").at(-1) ?? "")}`);
 };
 
 const moduleUrl: string | undefined = import.meta.url;

package/scripts/package/host-links.mjs

@@ -15,11 +15,11 @@ const workspaceFolders = (root) => [
 const nameOf = (folder) => {
   const file = path.join(folder, "package.json");
   const name = JSON.parse(readFileSync(file, "utf8")).name;
-  if (typeof name !== "string" || !name) throw new Error(`${file} nennt keinen Paketnamen`);
+  if (typeof name !== "string" || !name) throw new Error(`${file} names no package name`);
   return name;
 };
 
-/** Legt im Paket @schlenkr/ragents die Verknüpfungen an, die im Checkout von pnpm kommen; im Checkout tut sie nichts. */
+/** Creates in the package @schlenkr/ragents the links that pnpm creates in the checkout; in the checkout it does nothing. */
 export const ensureHostLinks = (root) => {
   const manifest = path.join(root, "package.json");
   if (!isFile(manifest) || JSON.parse(readFileSync(manifest, "utf8")).ragents?.hostVersion === undefined) return [];
@@ -28,7 +28,7 @@ export const ensureHostLinks = (root) => {
     const link = path.join(root, "node_modules", nameOf(folder));
     const existing = lstatSync(link, { throwIfNoEntry: false });
     if (existing) {
-      if (realpathSync(link) !== realpathSync(folder)) throw new Error(`${link} zeigt nicht auf ${folder}; das Paket ist beschädigt`);
+      if (realpathSync(link) !== realpathSync(folder)) throw new Error(`${link} does not point to ${folder}; the package is damaged`);
       continue;
     }
     mkdirSync(path.dirname(link), { recursive: true });

package/scripts/package/publish-package.ts

@@ -6,11 +6,11 @@ import { buildPackage, PACKAGE_FOLDER, PACKAGE_NAME } from "./build-package.ts";
 
 const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 
-const usage = `Verwendung: pnpm publish:package [--dry-run]
-Baut das Paket ${PACKAGE_NAME} und veröffentlicht es auf npm. Der Token kommt aus der
-Umgebungsvariable npm_key. --dry-run reicht npm den Probelauf durch und veröffentlicht nichts.
-Die Fassung steht in der package.json der Wurzel; das Skript zählt vor dem Bauen die letzte Stelle
-über die zuletzt veröffentlichte hoch, im Probelauf nur in der Ausgabe.`;
+const usage = `Usage: pnpm publish:package [--dry-run]
+Builds the package ${PACKAGE_NAME} and publishes it on npm. The token comes from the
+environment variable npm_key. --dry-run passes the dry run through to npm and publishes nothing.
+The version is in the root package.json; before building, the script raises the last place
+above the last published version, in a dry run only in the output.`;
 
 const REGISTRY_TOKEN_KEY = "npm_config_//registry.npmjs.org/:_authToken";
 
@@ -22,14 +22,14 @@ export interface NpmResult {
 
 export type NpmRunner = (args: readonly string[], options: { cwd: string; token?: string }) => NpmResult;
 
-/** Der Token geht nur als Konfiguration in die Umgebung des Kindprozesses, nie auf die Kommandozeile. */
+/** The token goes only as configuration into the child process's environment, never onto the command line. */
 export const publishEnvironment = (token: string, base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv =>
   ({ ...base, [REGISTRY_TOKEN_KEY]: token });
 
-/** Alles, was von npm kommt, geht durch diese Maske, damit der Token auch in einer Fehlermeldung nicht auftaucht. */
+/** Everything that comes from npm goes through this mask so that the token does not show up even in an error message. */
 export const redacting = (token: string) => (text: string): string => token ? text.split(token).join("<npm_key>") : text;
 
-/** Eine Fehlermeldung ist eine Zeile; die Ausgabe von npm wandert deshalb auf eine. */
+/** An error message is one line; npm's output is therefore moved onto one. */
 export const oneLine = (text: string): string => text.split("\n").map((line) => line.trim()).filter(Boolean).join("; ");
 
 const runNpm: NpmRunner = (args, options) => {
@@ -39,22 +39,22 @@ const runNpm: NpmRunner = (args, options) => {
     env: options.token ? publishEnvironment(options.token) : process.env,
     stdio: ["ignore", "pipe", "pipe"],
   });
-  if (result.error) throw new Error(`npm ${args[0]} konnte nicht gestartet werden: ${result.error.message}`);
+  if (result.error) throw new Error(`npm ${args[0]} could not be started: ${result.error.message}`);
   return { status: result.status ?? 1, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
 };
 
-/** Die Fassungen, die schon auf npm liegen; ein dort unbekanntes Paket ist die leere Liste, kein Fehler. */
+/** The versions already on npm; a package unknown there is the empty list, not an error. */
 export const publishedVersions = (name: string, npm: NpmRunner): readonly string[] => {
   const result = npm(["view", name, "versions", "--json"], { cwd: repositoryRoot });
   if (result.status !== 0) {
     if (/E404|404 Not Found/.test(`${result.stdout}\n${result.stderr}`)) return [];
-    throw new Error(`npm view ${name} versions endete mit Code ${result.status}: ${oneLine(result.stderr)}`);
+    throw new Error(`npm view ${name} versions ended with code ${result.status}: ${oneLine(result.stderr)}`);
   }
   const parsed = JSON.parse(result.stdout.trim() || "[]") as string | readonly string[];
   return typeof parsed === "string" ? [parsed] : parsed;
 };
 
-/** Die höchste Fassung, die auf npm liegt; ein dort unbekanntes Paket hat keine. */
+/** The highest version on npm; a package unknown there has none. */
 export const latestPublishedVersion = (npm: NpmRunner = runNpm, name = PACKAGE_NAME): string | undefined =>
   [...publishedVersions(name, npm)].sort(compareVersions).at(-1);
 
@@ -64,22 +64,22 @@ export interface PublishPlan {
   readonly hostVersion: string;
 }
 
-/** Was vor einem Publish stimmen muss: das gebaute Manifest und eine Fassung, die es auf npm noch nicht gibt. */
+/** What must be right before a publish: the built manifest and a version that does not yet exist on npm. */
 export const publishPlan = (manifest: Record<string, unknown>, published: readonly string[], version: string): PublishPlan => {
   const { name } = manifest as { name?: unknown };
   const access = (manifest.publishConfig as { access?: unknown } | undefined)?.access;
   const hostVersion = (manifest.ragents as { hostVersion?: unknown } | undefined)?.hostVersion;
-  if (name !== PACKAGE_NAME) throw new Error(`Das gebaute Paket heißt ${String(name)}, veröffentlicht wird ${PACKAGE_NAME}`);
-  if (access !== "public") throw new Error(`${PACKAGE_NAME} hat einen Scope und braucht publishConfig.access "public", nicht ${JSON.stringify(access)}`);
+  if (name !== PACKAGE_NAME) throw new Error(`The built package is named ${String(name)}, but ${PACKAGE_NAME} is published`);
+  if (access !== "public") throw new Error(`${PACKAGE_NAME} has a scope and needs publishConfig.access "public", not ${JSON.stringify(access)}`);
   if (!/^\d+\.\d+\.\d+(?:-[0-9a-z.-]+)?$/.test(version)) {
-    throw new Error(`Die Fassung ${JSON.stringify(version)} ist keine Fassung; sie steht als version in der package.json der Wurzel`);
+    throw new Error(`The version ${JSON.stringify(version)} is not a version; it is the version in the root package.json`);
   }
   if (typeof hostVersion !== "string" || !/^[0-9a-f]{40}$/.test(hostVersion)) {
-    throw new Error("Dem Paket fehlt ragents.hostVersion als vollständiger Git-Commit; gebaut wird nur aus einem Checkout");
+    throw new Error("The package lacks ragents.hostVersion as a full Git commit; it is built only from a checkout");
   }
   if (published.includes(version)) {
-    throw new Error(`${PACKAGE_NAME}@${version} liegt schon auf npm (dort: ${published.join(", ")}); `
-      + "erhöhe version in der package.json der Wurzel und baue neu");
+    throw new Error(`${PACKAGE_NAME}@${version} is already on npm (there: ${published.join(", ")}); `
+      + "raise version in the root package.json and rebuild");
   }
   return { name: PACKAGE_NAME, version, hostVersion };
 };
@@ -93,32 +93,32 @@ export interface PublishOptions {
   readonly log: (line: string) => void;
 }
 
-/** npm meldet eine fehlende Organisation als 404; ohne den Hinweis sucht man den Fehler beim Paket. */
+/** npm reports a missing organization as 404; without the hint you look for the error in the package. */
 const scopeAdvice = (output: string): string => /Scope not found/i.test(output)
-  ? ` Die Organisation ${PACKAGE_NAME.split("/")[0]} existiert auf npm nicht oder der Token darf sie nicht: `
-    + "auf npmjs.com anlegen bzw. den Token für den Scope freigeben."
+  ? ` The organization ${PACKAGE_NAME.split("/")[0]} does not exist on npm or the token may not use it: `
+    + "create it on npmjs.com or grant the token access to the scope."
   : "";
 
-/** Veröffentlicht den gebauten Ordner; der Exit 0 von npm publish ist die Bestätigung. */
+/** Publishes the built folder; exit 0 of npm publish is the confirmation. */
 export const publishDirectory = (options: PublishOptions): void => {
   const hide = redacting(options.token);
   const published = options.npm(["publish", "--access", "public", ...options.dryRun ? ["--dry-run"] : []], { cwd: options.directory, token: options.token });
   const output = `${published.stdout}${published.stderr}`;
   for (const line of output.split("\n")) if (line.trim()) options.log(hide(line));
-  if (published.status !== 0) throw new Error(`npm publish endete mit Code ${published.status}.${scopeAdvice(output)}`);
+  if (published.status !== 0) throw new Error(`npm publish ended with code ${published.status}.${scopeAdvice(output)}`);
   if (options.dryRun) {
-    options.log("== Probelauf: nichts veröffentlicht");
+    options.log("== Dry run: nothing published");
     return;
   }
-  options.log(`== Veröffentlicht: ${PACKAGE_NAME}@${options.version}`);
+  options.log(`== Published: ${PACKAGE_NAME}@${options.version}`);
 };
 
 const main = async (): Promise<void> => {
   const dryRun = process.argv.includes("--dry-run");
   const unknown = process.argv.slice(2).filter((argument) => argument !== "--dry-run");
-  if (unknown.length) throw new Error(`Unbekanntes Argument: ${unknown.join(" ")}\n${usage}`);
+  if (unknown.length) throw new Error(`Unknown argument: ${unknown.join(" ")}\n${usage}`);
   const token = process.env.npm_key;
-  if (!token) throw new Error(`npm_key fehlt: der npm-Token mit Schreibrecht auf ${PACKAGE_NAME}.\n${usage}`);
+  if (!token) throw new Error(`npm_key is missing: the npm token with write access to ${PACKAGE_NAME}.\n${usage}`);
   const manifestFile = path.join(repositoryRoot, "package.json");
   const published = publishedVersions(PACKAGE_NAME, runNpm);
   const extensionManifestFile = path.join(repositoryRoot, "apps", "vscode", "package.json");
@@ -131,7 +131,7 @@ const main = async (): Promise<void> => {
   }
   const built = await buildPackage(path.join(repositoryRoot, "dist", PACKAGE_FOLDER));
   const plan = publishPlan(built.manifest, published, next.version);
-  console.log(`== ${plan.name}@${plan.version} aus Host ${plan.hostVersion.slice(0, 12)}, ${built.fileCount} Dateien, ${(built.byteSize / 1024 / 1024).toFixed(1)} MB`);
+  console.log(`== ${plan.name}@${plan.version} from host ${plan.hostVersion.slice(0, 12)}, ${built.fileCount} files, ${(built.byteSize / 1024 / 1024).toFixed(1)} MB`);
   publishDirectory({ directory: built.directory, version: plan.version, token, dryRun, npm: runNpm, log: (line) => console.log(line) });
 };
 

package/scripts/package/ragents.mjs

@@ -19,24 +19,24 @@ export const commands = {
   stop: AGENT_CLI,
 };
 
-const usage = `Verwendung: ragents <befehl> [argumente]
+const usage = `Usage: ragents <command> [arguments]
 
-  run <ordner> "<auftrag>"         Host ohne Oberfläche starten, Run anlegen und auf das Ende warten
-  send <run> "<text>"              Folgeauftrag im selben Run
-  journal <run> [--tools]          Verlauf eines Runs lesen
-  stop <run> | stop --host         laufenden Turn abbrechen oder den gemerkten Host beenden
-  connect <server-url>             Client-Profil samt Bundles holen und den lokalen Server damit starten
-  start <profil|pfad>              ein Profil des Pakets, eine eigene Profildatei oder einen
-                                   geholten Stand starten; die Oberfläche kommt fertig mit
-  provision [<profil>|--workspace] Werkzeuge der Plugins holen
-  workspace-client <server-url>    diesen Rechner als Arbeitsplatz anmelden
-  plugin build <ordner...>         Plugin-Quellordner zu Bundles bauen (--out, --watch)
-  --help, help                     diese Verwendung
+  run <folder> "<task>"            start the host without UI, create a run and wait for the end
+  send <run> "<text>"              follow-up task in the same run
+  journal <run> [--tools]          read the history of a run
+  stop <run> | stop --host         cancel the running turn or stop the remembered host
+  connect <server-url>             fetch the client profile with its bundles and start the local server with it
+  start <profile|path>             start a profile of the package, an own profile file or a
+                                   fetched stand; the UI comes prebuilt
+  provision [<profile>|--workspace] fetch the plugins' tools
+  workspace-client <server-url>    register this machine as a workspace
+  plugin build <folder...>         build plugin source folders into bundles (--out, --watch)
+  --help, help                     this usage
 
-run, send, journal und stop nehmen mit --profile <profil|pfad> ein anderes Profil: einen Namen
-neben dem Host oder den Pfad zu einer eigenen ragents.config.<profil>.ts. RAGENTS_PROFILE setzt
-dasselbe für alle Befehle einer Shell; verlangt das Profil eine Anmeldung, gehört der
-persönliche Token des Benutzers in RAGENTS_TOKEN.
+run, send, journal and stop take another profile with --profile <profile|path>: a name
+next to the host or the path to an own ragents.config.<profile>.ts. RAGENTS_PROFILE sets
+the same for all commands of a shell; if the profile requires sign-in, the user's
+personal token goes into RAGENTS_TOKEN.
 `;
 
 const main = () => {
@@ -48,7 +48,7 @@ const main = () => {
   }
   const script = command ? commands[command] : undefined;
   if (!script) {
-    console.error(command ? `Unbekannter Befehl: ${command}\n\n${usage}` : usage);
+    console.error(command ? `Unknown command: ${command}\n\n${usage}` : usage);
     process.exit(1);
   }
   ensureHostLinks(root);
@@ -62,11 +62,11 @@ const main = () => {
   process.on("SIGINT", forward("SIGINT"));
   process.on("SIGTERM", forward("SIGTERM"));
   child.once("error", (error) => {
-    console.error(`ragents ${command} konnte nicht gestartet werden: ${error.message}`);
+    console.error(`ragents ${command} could not be started: ${error.message}`);
     process.exit(1);
   });
   child.once("exit", (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
 };
 
-// npm legt den Befehl als Verknüpfung ab; der Vergleich braucht deshalb den echten Pfad.
+// npm installs the command as a link; the comparison therefore needs the real path.
 if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) main();

package/scripts/plugin/build-builtin-plugins.ts

@@ -20,25 +20,25 @@ const removeOrphans = async (folders: readonly string[]): Promise<void> => {
     .filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && !ids.has(entry.name));
   for (const orphan of orphans) {
     await rm(path.join(bundlesRoot, orphan.name), { recursive: true, force: true });
-    console.log(`entfernt: ${orphan.name} (kein Quellordner mehr)`);
+    console.log(`removed: ${orphan.name} (no source folder anymore)`);
   }
 };
 
-// Ohne Typprüfung, weil pnpm -r typecheck die Quellen schon prüft; nur Veraltetes, damit laufende Server und parallele Bauläufe ihre Bundles behalten.
+// Without type checking, because pnpm -r typecheck already checks the sources; only outdated ones, so running servers and parallel builds keep their bundles.
 const main = async (argv: readonly string[]): Promise<number> => {
   const unknown = argv.filter((argument) => argument !== "--watch");
-  if (unknown.length > 0) throw new Error(`Unbekanntes Argument: ${unknown.join(" ")} (erlaubt: --watch)`);
+  if (unknown.length > 0) throw new Error(`Unknown argument: ${unknown.join(" ")} (allowed: --watch)`);
   const folders = builtInPluginFolders();
   if (argv.includes("--watch")) {
     const watching = await watchPlugins(folders, { out: bundlesRoot }, printOutcome);
-    console.log(`beobachte ${folders.length} eingebaute Plugins; Strg+C beendet`);
+    console.log(`watching ${folders.length} built-in plugins; Ctrl+C stops`);
     await untilStopped();
     await watching.stop();
     return 0;
   }
   const outcomes = await buildPlugins(folders, { out: bundlesRoot, typecheck: false, onlyOutdated: true });
   for (const outcome of outcomes) printOutcome(outcome);
-  if (outcomes.length < folders.length) console.log(`aktuell: ${folders.length - outcomes.length} von ${folders.length} eingebauten Plugins, unverändert gelassen`);
+  if (outcomes.length < folders.length) console.log(`up to date: ${folders.length - outcomes.length} of ${folders.length} built-in plugins, left unchanged`);
   await removeOrphans(folders);
   return outcomes.every((outcome) => outcome.kind === "built") ? 0 : 1;
 };

package/scripts/plugin/plugin-cli.ts

@@ -5,14 +5,14 @@ import { callerDirectory } from "../../apps/server/src/profile-target.ts";
 
 export const DEFAULT_OUT = "dist/plugins";
 
-export const usage = (): string => `Verwendung: ragents plugin build <ordner...> [--out <ordner>] [--watch] [--no-typecheck]
+export const usage = (): string => `Usage: ragents plugin build <folder...> [--out <folder>] [--watch] [--no-typecheck]
 
-Baut jeden Plugin-Quellordner mit ragents-plugin.json zu einem Bundle unter <out>/<kennung>,
-Vorgabe ./${DEFAULT_OUT}. Ein Bundle darf vom Host nur die Host-API beziehen und von anderen
-Plugins nur deren deklarierte Exporte; jede andere Stelle, ein Dateizugriff über den eigenen Ort
-(import.meta.url, __dirname, createRequire), eine Binärdatei (.node) und jeder Typfehler brechen
-den Bau mit Ursache ab. --watch baut bei jeder Änderung im Ordner neu und prüft keine Typen, das
-tut der Editor. Exit-Code 0, wenn alle Plugins gebaut sind, sonst 1.`;
+Builds every plugin source folder with ragents-plugin.json into a bundle under <out>/<id>,
+default ./${DEFAULT_OUT}. A bundle may take only the host API from the host and only their
+declared exports from other plugins; any other location, a file access relative to its own
+location (import.meta.url, __dirname, createRequire), a binary file (.node) and every type
+error abort the build with the cause. --watch rebuilds on every change in the folder and does
+not check types, the editor does that. Exit code 0 if all plugins are built, otherwise 1.`;
 
 export interface PluginCommand {
   readonly folders: readonly string[];
@@ -23,7 +23,7 @@ export interface PluginCommand {
 
 export const parsePluginArguments = (argv: readonly string[], caller = callerDirectory()): PluginCommand => {
   const [command, ...rest] = argv;
-  if (command !== "build") throw new Error(command ? `Unbekannter Befehl: plugin ${command}\n\n${usage()}` : usage());
+  if (command !== "build") throw new Error(command ? `Unknown command: plugin ${command}\n\n${usage()}` : usage());
   const folders: string[] = [];
   const switches = new Set<string>();
   let out: string | undefined;
@@ -31,18 +31,18 @@ export const parsePluginArguments = (argv: readonly string[], caller = callerDir
     const argument = rest[index]!;
     if (argument === "--out") {
       const value = rest[index + 1];
-      if (value === undefined || value.startsWith("--")) throw new Error("--out braucht einen Ordner.");
+      if (value === undefined || value.startsWith("--")) throw new Error("--out needs a folder.");
       out = value;
       index += 1;
     } else if (argument === "--watch" || argument === "--no-typecheck") {
       switches.add(argument);
     } else if (argument.startsWith("--")) {
-      throw new Error(`Unbekanntes Argument: ${argument}\n\n${usage()}`);
+      throw new Error(`Unknown argument: ${argument}\n\n${usage()}`);
     } else {
       folders.push(path.resolve(caller, argument));
     }
   }
-  if (folders.length === 0) throw new Error(`plugin build braucht mindestens einen Plugin-Ordner.\n\n${usage()}`);
+  if (folders.length === 0) throw new Error(`plugin build needs at least one plugin folder.\n\n${usage()}`);
   return {
     folders,
     out: path.resolve(caller, out ?? DEFAULT_OUT),
@@ -58,8 +58,8 @@ const shown = (folder: string, caller: string): string => {
 
 export const outcomeLines = (outcome: PluginBuildOutcome, caller = callerDirectory()): readonly string[] =>
   outcome.kind === "built"
-    ? [`gebaut: ${outcome.id} -> ${shown(outcome.bundle, caller)} (${outcome.milliseconds} ms${outcome.manifest.uses.length > 0 ? `, nutzt ${outcome.manifest.uses.join(", ")}` : ""})`]
-    : [`fehlgeschlagen: ${outcome.id} (${shown(outcome.source, caller)})`, ...outcome.problems.map((problem) => `  ${problem.replaceAll("\n", "\n  ")}`)];
+    ? [`built: ${outcome.id} -> ${shown(outcome.bundle, caller)} (${outcome.milliseconds} ms${outcome.manifest.uses.length > 0 ? `, uses ${outcome.manifest.uses.join(", ")}` : ""})`]
+    : [`failed: ${outcome.id} (${shown(outcome.source, caller)})`, ...outcome.problems.map((problem) => `  ${problem.replaceAll("\n", "\n  ")}`)];
 
 export const printOutcome = (outcome: PluginBuildOutcome): void => {
   const lines = outcomeLines(outcome).join("\n");
@@ -80,7 +80,7 @@ export const main = async (argv: readonly string[]): Promise<number> => {
   const command = parsePluginArguments(argv);
   if (command.watch) {
     const watching = await watchPlugins(command.folders, { out: command.out }, printOutcome);
-    console.log(`beobachte ${command.folders.length} Plugin-Ordner; Strg+C beendet`);
+    console.log(`watching ${command.folders.length} plugin folders; Ctrl+C stops`);
     await untilStopped();
     await watching.stop();
     return 0;

package/scripts/provision/run-provision.ts

@@ -17,22 +17,21 @@ const PROFILE_FILE = /^ragents\.config\.([a-z0-9]+(?:-[a-z0-9]+)*)\.ts$/;
 
 const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 
-const usage = (): string => `Verwendung: pnpm provision [<profil>|<pfad zu ragents.config.<profil>.ts>|--workspace]
-Provisioniert die Werkzeuge der Plugins eines Profils nach <Datenordner>/tools/<plugin-id>/ und
-berichtet je Plugin bereit, installiert oder fehlt. --workspace provisioniert stattdessen die
-eingebauten Plugins, die zum Executor eines Arbeitsplatzes beitragen. Ein relativer Pfad gilt ab dem
-aufrufenden Ordner; ohne Argument gilt das Profil aus der Umgebung (PRODUCT_PROFILE_FILE oder
-PRODUCT_PROFILE).`;
+const usage = (): string => `Usage: pnpm provision [<profile>|<path to ragents.config.<profile>.ts>|--workspace]
+Provisions the tools of a profile's plugins to <data folder>/tools/<plugin-id>/ and reports per
+plugin ready, installed or missing. --workspace instead provisions the built-in plugins that
+contribute to a workspace's executor. A relative path is resolved from the calling folder; without
+an argument the profile from the environment applies (PRODUCT_PROFILE_FILE or PRODUCT_PROFILE).`;
 
 const availableProfiles = (): readonly string[] => readdirSync(repositoryRoot)
   .map((name) => PROFILE_FILE.exec(name)?.[1])
   .filter((name): name is string => name !== undefined && name !== "example")
   .sort();
 
-/** Ein Name gilt neben dem Host, ein Pfad ab dem Aufrufer, wie bei ragents start. */
+/** A name applies next to the host, a path from the caller, as with ragents start. */
 export const selectedProfile = (selection: string, root = repositoryRoot, caller = callerDirectory()): { profile: string; file: string } => {
   const own = localProfile(selection, root, caller);
-  if (!own) throw new Error(`Konfiguration fehlt: ${path.join(root, profileFileName(selection))}`);
+  if (!own) throw new Error(`Configuration is missing: ${path.join(root, profileFileName(selection))}`);
   return { profile: own.profile, file: own.profileFile };
 };
 
@@ -42,26 +41,26 @@ const forProfile = async (selection: string): Promise<readonly PluginProvisionRe
   process.env.PRODUCT_PROFILE_FILE = file;
   await loadConfigFile();
   const { config } = await import("../../apps/server/src/config.ts");
-  console.log(`== Provisionierung Profil ${profile} (${file})`);
-  console.log(`== Werkzeuge unter ${path.join(config.dataDir, "tools")}`);
+  console.log(`== Provisioning profile ${profile} (${file})`);
+  console.log(`== Tools under ${path.join(config.dataDir, "tools")}`);
   return provisionPlugins(resolvePluginEntries(config.plugins), config.dataDir, (line) => console.log(line));
 };
 
 const forWorkspace = (): Promise<readonly PluginProvisionReport[]> => {
-  console.log("== Provisionierung Arbeitsplatz");
-  console.log(`== Werkzeuge unter ${path.join(hostDataDirectory(), "tools")}`);
+  console.log("== Provisioning workspace");
+  console.log(`== Tools under ${path.join(hostDataDirectory(), "tools")}`);
   return provisionWorkspace((line) => console.log(line));
 };
 
 const main = async (): Promise<void> => {
   const argv = process.argv.slice(2);
   if (argv.length > 1 || argv.some((argument) => argument.startsWith("-") && argument !== "--workspace")) {
-    throw new Error(`Unerwartete Argumente: ${argv.join(" ")}\n${usage()}`);
+    throw new Error(`Unexpected arguments: ${argv.join(" ")}\n${usage()}`);
   }
   const selection = argv[0] ?? process.env.PRODUCT_PROFILE_FILE ?? process.env.PRODUCT_PROFILE;
-  if (!selection) throw new Error(`Kein Profil genannt; im Repository liegen ${availableProfiles().join(", ")}.\n${usage()}`);
+  if (!selection) throw new Error(`No profile named; the repository contains ${availableProfiles().join(", ")}.\n${usage()}`);
   const reports = selection === "--workspace" ? await forWorkspace() : await forProfile(selection);
-  if (reports.length === 0) console.log("Kein Plugin bringt eine Provisionierung mit.");
+  if (reports.length === 0) console.log("No plugin brings a provisioning.");
   if (reports.some((report) => report.outcome === "missing")) process.exitCode = 1;
 };