@schlenkr/ragents 0.1.5 → 0.1.6

package/scripts/package/build-package.ts

@@ -5,7 +5,10 @@ import { builtinModules } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { readHostVersion, readPackageVersion } from "../../apps/server/src/host-version.ts";
-import { runtimeLibraries } from "../../plugins/ragents.actor-programs/server/runtime-libraries.ts";
+import { hostWebDirectory, hostWebProblem, isCheckout } from "../../apps/server/src/host-web.ts";
+import { runtimeLibraries } from "../../apps/server/src/plugin-support/actor-programs/runtime-libraries.ts";
+import { assertBundleStand, readBundleManifest, sourceStandOf } from "../../apps/server/src/profile/bundle-manifest.ts";
+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. */
@@ -39,42 +42,54 @@ 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, Plugins, Profile, den Web-Build und die Skripte hinter den Unterbefehlen. */
+/** 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. */
 export const packageContents = (root = repositoryRoot): readonly string[] => [
   "apps/server/package.json",
   "apps/server/tsconfig.json",
+  "apps/server/tsconfig.plugin.json",
   "apps/server/src",
-  "apps/server/agent-home/settings.json",
   "apps/web/package.json",
   "apps/web/tsconfig.json",
-  "apps/web/vite.config.ts",
-  "apps/web/index.html",
-  "apps/web/column.html",
+  "apps/web/tsconfig.plugin.json",
   "apps/web/src",
+  "apps/web/dist",
   ...readdirSync(path.join(root, "packages"), { withFileTypes: true })
     .filter((entry) => entry.isDirectory())
     .flatMap((entry) => [`packages/${entry.name}/package.json`, `packages/${entry.name}/src`]),
+  "bundles",
   "plugins",
   ...PACKAGED_PROFILES.map((profile) => `ragents.config.${profile}.ts`),
   "scripts/agent",
   "scripts/package",
+  "scripts/plugin",
   "scripts/provision",
   "scripts/remote",
   "scripts/workspace-client",
 ];
 
-/** Was der Host ausführt, in eine Mini-App bündelt oder beim Start in sein Web baut. */
+/** Die gegabelte Agentenlaufzeit läuft aus ihren Quellen, ihre Typen gibt es nur gebaut; das Bauwerkzeug prüft fremde Plugins gegen sie. */
+export const declarationFolders = (root = repositoryRoot): readonly string[] =>
+  readdirSync(path.join(root, "packages"), { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .filter((entry) => {
+      const manifest = path.join(root, "packages", entry.name, "package.json");
+      const types = statSync(manifest, { throwIfNoEntry: false })?.isFile() ? (JSON.parse(readFileSync(manifest, "utf8")) as { types?: unknown }).types : undefined;
+      return typeof types === "string" && types.startsWith("./dist/");
+    })
+    .map((entry) => `packages/${entry.name}/dist`);
+
+/** Was der Host ausführt, in eine Mini-App bündelt oder beim Bauen eines Plugins liest. */
 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;
 
-const files = async (folder: string): Promise<readonly string[]> => {
+const files = async (folder: string, skippedFolders: ReadonlySet<string> = SKIPPED_FOLDERS): Promise<readonly string[]> => {
   const found: string[] = [];
   for (const entry of (await readdir(folder, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name, "en"))) {
     if (entry.isDirectory()) {
-      if (!SKIPPED_FOLDERS.has(entry.name)) found.push(...await files(path.join(folder, entry.name)));
+      if (!skippedFolders.has(entry.name)) found.push(...await files(path.join(folder, entry.name), skippedFolders));
     } else if (entry.isFile() && !SKIPPED_FILES.has(entry.name)) {
       found.push(path.join(folder, entry.name));
     }
@@ -82,7 +97,7 @@ const files = async (folder: string): Promise<readonly string[]> => {
   return found;
 };
 
-const copyTo = async (source: string, target: string, packageRoot: string): Promise<readonly string[]> => {
+const copyTo = async (source: string, target: string, packageRoot: string, skippedFolders?: ReadonlySet<string>): Promise<readonly string[]> => {
   if (statSync(source).isFile()) {
     if (skippedInPackage(packagePath(packageRoot, target))) return [];
     await mkdir(path.dirname(target), { recursive: true });
@@ -90,7 +105,7 @@ const copyTo = async (source: string, target: string, packageRoot: string): Prom
     return [target];
   }
   const copied: string[] = [];
-  for (const file of await files(source)) {
+  for (const file of await files(source, skippedFolders)) {
     const destination = path.join(target, path.relative(source, file));
     if (skippedInPackage(packagePath(packageRoot, destination))) continue;
     await mkdir(path.dirname(destination), { recursive: true });
@@ -112,7 +127,7 @@ const scannedFiles = (folder: string): readonly string[] => {
 };
 
 const packageNameOf = (specifier: string): string | undefined => {
-  if (/^(\.{1,2}\/|\/|node:|data:|@aicontainer\/|@ragents\/|virtual:)/.test(specifier) || specifier === "vscode") return undefined;
+  if (/^(\.{1,2}\/|\/|node:|data:|@ragents\/|virtual:)/.test(specifier) || specifier === "vscode") return undefined;
   const parts = specifier.split("/");
   const name = specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0]!;
   if (builtinModules.includes(name)) return undefined;
@@ -188,16 +203,56 @@ export interface BuiltPackage {
   readonly flattened: readonly string[];
 }
 
+/** Das Paket liefert das Web fertig aus; es muss gebaut sein und zu seinen Quellen passen. */
+const assertHostWeb = (root: string): void => {
+  const problem = hostWebProblem(hostWebDirectory(root), root, isCheckout(root));
+  if (problem) throw new Error(`${problem}; vorher pnpm build:web`);
+};
+
+/** Jedes eingebaute Plugin muss als Bundle vorliegen und zu seinen Quellen passen, sonst startet das Paket kein Profil. */
+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`);
+  }
+};
+
+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`);
+    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 });
+      await copyFile(file, destination);
+      copied.push(destination);
+    }
+  }
+  return copied;
+};
+
 export const buildPackage = async (target: string, root = repositoryRoot): Promise<BuiltPackage> => {
+  assertBuiltInBundles(root);
+  assertHostWeb(root);
   await rm(target, { recursive: true, force: true });
   await mkdir(target, { recursive: true });
   let fileCount = 0;
   let byteSize = 0;
   for (const entry of packageContents(root)) {
-    const copied = await copyTo(path.join(root, entry), path.join(target, entry), target);
+    // Ein Bundle ist fertig gebaut und kommt ganz ins Paket, auch ein Asset-Ordner namens 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;
   }
+  for (const folder of builtInPluginFolders(path.join(root, "plugins"))) {
+    const bundle = path.join(target, "bundles", path.basename(folder));
+    assertBundleStand(bundle, readBundleManifest(bundle));
+  }
+  for (const file of await copyDeclarations(root, target)) {
+    fileCount += 1;
+    byteSize += statSync(file).size;
+  }
   for (const [source, packaged] of PACKAGE_ROOT_FILES) {
     const destination = path.join(target, packaged);
     await mkdir(path.dirname(destination), { recursive: true });

package/scripts/package/ragents.mjs

@@ -12,6 +12,7 @@ export const commands = {
   start: "scripts/remote/start.ts",
   provision: "scripts/provision/run-provision.ts",
   "workspace-client": "scripts/workspace-client/run-workspace-client.ts",
+  plugin: "scripts/plugin/plugin-cli.ts",
   run: AGENT_CLI,
   send: AGENT_CLI,
   journal: AGENT_CLI,
@@ -24,11 +25,12 @@ const usage = `Verwendung: ragents <befehl> [argumente]
   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 holen und den lokalen Server damit starten
+  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; baut die Oberfläche bei Bedarf
+                                   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, send, journal und stop nehmen mit --profile <profil|pfad> ein anderes Profil: einen Namen

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

@@ -0,0 +1,52 @@
+import { existsSync, readdirSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildPlugins, watchPlugins } from "../../apps/server/src/plugin-build/build.ts";
+import { bundlesRoot, pluginsRoot } from "../../apps/server/src/plugin-support/plugins-root.ts";
+import { printOutcome, untilStopped } from "./plugin-cli.ts";
+
+/** Every plugin of the host that describes itself in ragents-plugin.json. */
+export const builtInPluginFolders = (root = pluginsRoot): readonly string[] =>
+  readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(path.join(root, entry.name, "ragents-plugin.json")))
+    .map((entry) => path.join(root, entry.name))
+    .sort();
+
+/** Removes bundles whose plugin no longer exists, so that no id resolves to an orphan. */
+const removeOrphans = async (folders: readonly string[]): Promise<void> => {
+  const ids = new Set(folders.map((folder) => path.basename(folder)));
+  const orphans = readdirSync(bundlesRoot, { withFileTypes: true })
+    .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)`);
+  }
+};
+
+// Ohne Typprüfung, weil pnpm -r typecheck die Quellen schon prüft; nur Veraltetes, damit laufende Server und parallele Bauläufe ihre Bundles behalten.
+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)`);
+  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`);
+    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`);
+  await removeOrphans(folders);
+  return outcomes.every((outcome) => outcome.kind === "built") ? 0 : 1;
+};
+
+const moduleUrl: string | undefined = import.meta.url;
+if (moduleUrl && process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(moduleUrl)) {
+  main(process.argv.slice(2)).then((code) => process.exit(code), (error: unknown) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}

package/scripts/plugin/plugin-cli.ts

@@ -0,0 +1,99 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildPlugins, watchPlugins, type PluginBuildOutcome } from "../../apps/server/src/plugin-build/build.ts";
+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]
+
+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.`;
+
+export interface PluginCommand {
+  readonly folders: readonly string[];
+  readonly out: string;
+  readonly watch: boolean;
+  readonly typecheck: boolean;
+}
+
+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());
+  const folders: string[] = [];
+  const switches = new Set<string>();
+  let out: string | undefined;
+  for (let index = 0; index < rest.length; index += 1) {
+    const argument = rest[index]!;
+    if (argument === "--out") {
+      const value = rest[index + 1];
+      if (value === undefined || value.startsWith("--")) throw new Error("--out braucht einen Ordner.");
+      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()}`);
+    } else {
+      folders.push(path.resolve(caller, argument));
+    }
+  }
+  if (folders.length === 0) throw new Error(`plugin build braucht mindestens einen Plugin-Ordner.\n\n${usage()}`);
+  return {
+    folders,
+    out: path.resolve(caller, out ?? DEFAULT_OUT),
+    watch: switches.has("--watch"),
+    typecheck: !switches.has("--no-typecheck") && !switches.has("--watch"),
+  };
+};
+
+const shown = (folder: string, caller: string): string => {
+  const relative = path.relative(caller, folder);
+  return relative.startsWith("..") ? folder : relative || ".";
+};
+
+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  ")}`)];
+
+export const printOutcome = (outcome: PluginBuildOutcome): void => {
+  const lines = outcomeLines(outcome).join("\n");
+  if (outcome.kind === "built") console.log(lines);
+  else console.error(lines);
+};
+
+export const untilStopped = (): Promise<void> => new Promise((resolve) => {
+  process.once("SIGINT", () => resolve());
+  process.once("SIGTERM", () => resolve());
+});
+
+export const main = async (argv: readonly string[]): Promise<number> => {
+  if (argv.length === 0 || argv[0] === "--help" || argv[0] === "help") {
+    console.log(usage());
+    return argv.length === 0 ? 1 : 0;
+  }
+  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`);
+    await untilStopped();
+    await watching.stop();
+    return 0;
+  }
+  const outcomes = await buildPlugins(command.folders, { out: command.out, typecheck: command.typecheck });
+  for (const outcome of outcomes) printOutcome(outcome);
+  return outcomes.every((outcome) => outcome.kind === "built") ? 0 : 1;
+};
+
+const moduleUrl: string | undefined = import.meta.url;
+if (moduleUrl && process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(moduleUrl)) {
+  main(process.argv.slice(2)).then((code) => process.exit(code), (error: unknown) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}

package/scripts/provision/run-provision.ts

@@ -1,9 +1,11 @@
 import "../../apps/server/src/host-resolution.ts";
-import { readdirSync, statSync } from "node:fs";
+import { readdirSync, realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { hostDataDirectory } from "@aicontainer/workspace-executor/src/tools.ts";
-import { loadConfigFile } from "../../apps/server/src/config-file.ts";
+import { hostDataDirectory } from "@ragents/workspace-executor/src/tools.ts";
+import { loadConfigFile, profileFileName } from "../../apps/server/src/config-file.ts";
+import { callerDirectory, localProfile } from "../../apps/server/src/profile-target.ts";
+import { reportMissingEnvironment } from "../../apps/server/src/missing-environment.ts";
 import { resolvePluginEntries } from "../../apps/server/src/profile/plugin-discovery.ts";
 import {
   provisionPlugins,
@@ -17,9 +19,9 @@ 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
-Sprachserver eines Arbeitsplatzes auf dieser Maschine. Ein relativer Pfad gilt ab der
-Repository-Wurzel; ohne Argument gilt das Profil aus der Umgebung (PRODUCT_PROFILE_FILE oder
+berichtet je Plugin bereit, installiert oder fehlt. --workspace provisioniert stattdessen
+Sprachserver und Browser eines Arbeitsplatzes auf dieser Maschine. Ein relativer Pfad gilt ab dem
+aufrufenden Ordner; ohne Argument gilt das Profil aus der Umgebung (PRODUCT_PROFILE_FILE oder
 PRODUCT_PROFILE).`;
 
 const availableProfiles = (): readonly string[] => readdirSync(repositoryRoot)
@@ -27,14 +29,11 @@ const availableProfiles = (): readonly string[] => readdirSync(repositoryRoot)
   .filter((name): name is string => name !== undefined && name !== "example")
   .sort();
 
-export const selectedProfile = (selection: string, root = repositoryRoot): { profile: string; file: string } => {
-  const file = selection.includes("/") || selection.endsWith(".ts")
-    ? path.resolve(root, selection)
-    : path.join(root, `ragents.config.${selection}.ts`);
-  const name = PROFILE_FILE.exec(path.basename(file));
-  if (!name) throw new Error(`Eine Profildatei heißt ragents.config.<profil>.ts: ${selection}`);
-  if (!statSync(file, { throwIfNoEntry: false })?.isFile()) throw new Error(`Konfiguration fehlt: ${file}`);
-  return { profile: name[1]!, file };
+/** Ein Name gilt neben dem Host, ein Pfad ab dem Aufrufer, wie bei 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))}`);
+  return { profile: own.profile, file: own.profileFile };
 };
 
 const forProfile = async (selection: string): Promise<readonly PluginProvisionReport[]> => {
@@ -66,7 +65,10 @@ const main = async (): Promise<void> => {
   if (reports.some((report) => report.outcome === "missing")) process.exitCode = 1;
 };
 
-await main().catch((error: unknown) => {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
-});
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+  await main().catch((error: unknown) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    reportMissingEnvironment(error, (line) => console.error(line));
+    process.exit(1);
+  });
+}